Трейт scala.concurrent.Future

трейт Future[+T] extends Awaitable[T]

A Future представляет значение, которое может или не может *в данный момент* быть доступным, но будет доступно в какой-то момент, или исключение, если это значение не могло быть сделано доступным.

Асинхронные вычисления, которые дают фьючерсы, создаются с помощью вызова Future.apply и вычисляются с помощью предоставленного ExecutionContext, который может быть обеспечен пулом потоков.

import ExecutionContext.Implicits.global
val s = "Hello"
val f: Future[String] = Future {
  s + " future!"
}
f foreach {
  msg => println(msg)
}

Обработчики событий

Исходный код

def andThen[U](pf: PartialFunction[Try[T], U])(implicit executor: ExecutionContext): Future[T]

Применяет функцию побочного эффекта к результату этого фьючерса и возвращает новый фьючерс с результатом этого фьючерса.

Этот метод позволяет гарантировать, что обработчики событий выполняются в заданном порядке.

Обратите внимание, что если один из цепочных обработчиков andThen вызывает исключение, это исключение не передается последующим обработчикам andThen. Вместо этого последующие обработчики andThen получают исходное значение этого фьючерса.

Следующий пример выводит 5:

val f = Future { 5 }
f andThen {
  case r => throw new RuntimeException("runtime exception")
} andThen {
  case Failure(t) => println(t)
  case Success(v) => println(v)
}

Поскольку этот метод выполняется асинхронно и не возвращает значение, любые некритические исключения, выброшенные в процессе, будут сообщены ExecutionContext.

Исходный код

def foreach[U](f: T => U)(implicit executor: ExecutionContext): Unit

Асинхронно обрабатывает значение в фьючерсе, как только оно станет доступным.

ВНИМАНИЕ: Не будет вызываться, если этот фьючерс никогда не завершится или если он завершится с ошибкой.

Поскольку этот метод выполняется асинхронно и не возвращает значение, любые некритические исключения, выброшенные в процессе, будут сообщены ExecutionContext.

Исходный код

def onComplete[U](f: Try[T] => U)(implicit executor: ExecutionContext): Unit

При завершении этого фьючерса, либо с исключением, либо со значением, примените предоставленную функцию.

Если фьючерс уже завершен, это будет применено немедленно или будет запланировано асинхронно.

Обратите внимание, что возвращаемое значение f будет проигнорировано.

Поскольку этот метод выполняется асинхронно и не возвращает значение, любые некритические исключения, выброшенные в процессе, будут сообщены ExecutionContext.

Несколько обработчиков событий могут быть зарегистрированы; нет гарантии, что они будут выполнены в определённом порядке.

Предоставленный обработчик всегда выполняется в предоставленном неявном ExecutionContext, хотя нет гарантии, что метод execute() на ExecutionContext будет вызван один раз на каждый обработчик или что execute() будет вызван в текущем потоке. То есть, реализация может выполнять несколько обработчиков в одной группе в рамках одного execute() и она может выполнять execute() немедленно или асинхронно. Завершение фьючерса должно *предшествовать* вызову обработчика.

Опрос

Исходный код

def isCompleted: Boolean

Возвращает, был ли фьючерс уже завершен со значением или исключением.

Примечание: использование этого метода приводит к недетерминированным программам обработки данных.

Исходный код

def value: Option[Try[T]]

Текущее значение этого Future.

Примечание: использование этого метода приводит к недетерминированным программам обработки данных.

Если фьючерс не был завершен, возвращаемое значение будет None. Если фьючерс был завершен, значение будет Some(Success(t)) если он содержал действительный результат, или Some(Failure(error)) если он содержал исключение.

Преобразования

Исходный код

def collect[S](pf: PartialFunction[T, S])(implicit executor: ExecutionContext): Future[S]

Создаёт новый фьючерс, отображая значение текущего фьючерса, если заданная частичная функция определена для этого значения.

Если текущий фьючерс содержит значение, для которого частичная функция определена, новый фьючерс также будет содержать это значение. В противном случае, результирующий фьючерс завершится с NoSuchElementException.

Если текущий фьючерс завершается с ошибкой, то и результирующий фьючерс завершается с ошибкой.

Пример:

val f = Future { -5 }
val g = f collect {
  case x if x < 0 => -x
}
val h = f collect {
  case x if x > 0 => x * 2
}
g foreach println // Eventually prints 5
Await.result(h, Duration.Zero) // throw a NoSuchElementException

Исходный код

def failed: Future[Throwable]

Возвращаемый Future будет успешно завершён с Throwable исходного Future если исходный Future завершится с ошибкой.

Если исходный Future завершается успешно, возвращаемый Future завершается с NoSuchElementException.

Этот фьючерс может содержать объект throwable, что означает, что фьючерс завершился с ошибкой. Фьючерсы, полученные с помощью комбинаторов, имеют то же самое исключение, что и фьючерс, из которого они были получены. Следующие объекты throwable не содержатся во фьючерсе: - Error - фатальные ошибки не содержатся во фьючерсах - InterruptedException - не содержатся во фьючерсах - все scala.util.control.ControlThrowable кроме NonLocalReturnControl - не содержатся во фьючерсах

Вместо этого фьючерс завершается с ExecutionException с одним из вышеперечисленных исключений в качестве причины. Если фьючерс завершается с scala.runtime.NonLocalReturnControl, он завершается со значением из этого throwable.

Исходный код

def fallbackTo[U >: T](that: Future[U]): Future[U]

Создаёт новый фьючерс, который содержит результат этого фьючерса, если он завершился успешно, или, если нет, результат фьючерса that если that завершается успешно. Если оба фьючерса завершаются с ошибкой, результирующий фьючерс содержит объект throwable первого фьючерса.

Использование этого метода не приведёт к тому, что конкурентные программы станут недетерминированными.

Пример:

val f = Future { throw new RuntimeException("failed") }
val g = Future { 5 }
val h = f fallbackTo g
h foreach println // Eventually prints 5

Источник

def filter(p: T => Boolean)(implicit executor: ExecutionContext): Future[T]

Создаёт новый фьючер, отфильтровывая значение текущего фьючера с помощью предиката.

Если текущий фьючер содержит значение, которое удовлетворяет предикату, то новый фьючер также будет содержать это значение. В противном случае, результирующий фьючер завершится с ошибкой NoSuchElementException.

Если текущий фьючер завершается с ошибкой, то результирующий фьючер также завершается с ошибкой.

Пример:

val f = Future { 5 }
val g = f filter { _ % 2 == 1 }
val h = f filter { _ % 2 == 0 }
g foreach println // Eventually prints 5
Await.result(h, Duration.Zero) // throw a NoSuchElementException

Источник

def flatMap[S](f: T => Future[S])(implicit executor: ExecutionContext): Future[S]

Создаёт новый фьючер, применяя функцию к успешному результату этого фьючера и возвращает результат функции как новый фьючер. Если этот фьючер завершился исключением, то новый фьючер также будет содержать это исключение.

Пример:

val f = Future { 5 }
val g = Future { 3 }
val h = for {
  x: Int <- f // returns Future(5)
  y: Int <- g // returns Future(3)
} yield x + y

преобразуется в:

f flatMap { (x: Int) => g map { (y: Int) => x + y } }

Источник

def flatten[S](implicit ev: T <:< Future[S]): Future[S]

Создаёт новый фьючер с одним уровнем вложенности, сглаженным. Этот метод эквивалентен flatMap(identity).

Источник

def map[S](f: T => S)(implicit executor: ExecutionContext): Future[S]

Создаёт новый фьючер, применяя функцию к успешному результату этого фьючера. Если этот фьючер завершается исключением, то новый фьючер также будет содержать это исключение.

Пример:

val f = Future { "The future" }
val g = f map { x: String => x + " is now!" }

Обратите внимание, что для выражения for, включающего Future , может быть включено вызов map и/или flatMap и withFilter. См. scala.concurrent.Future#flatMap для примера такого выражения.

Источник

def mapTo[S](implicit tag: ClassTag[S]): Future[S]

Создаёт новый Future[S] который завершается результатом этого Future если он соответствует стёртому типу S или ClassCastException в противном случае.

Источник

def recover[U >: T](pf: PartialFunction[Throwable, U])(implicit executor: ExecutionContext): Future[U]

Создаёт новый фьючер, который будет обрабатывать любые совпадающие исключения, которые этот фьючер может содержать. Если совпадений нет или этот фьючер содержит действительный результат, то новый фьючер будет содержать то же самое.

Пример:

Future (6 / 0) recover { case e: ArithmeticException => 0 } // result: 0
Future (6 / 0) recover { case e: NotFoundException   => 0 } // result: exception
Future (6 / 2) recover { case e: ArithmeticException => 0 } // result: 3

Источник

def recoverWith[U >: T](pf: PartialFunction[Throwable, Future[U]])(implicit executor: ExecutionContext): Future[U]

Создаёт новый фьючер, который будет обрабатывать любые совпадающие исключения, которые этот фьючер может содержать, назначив ему значение другого фьючера.

Если совпадений нет или этот фьючер содержит действительный результат, то новый фьючер будет содержать тот же результат.

Пример:

val f = Future { Int.MaxValue }
Future (6 / 0) recoverWith { case e: ArithmeticException => f } // result: Int.MaxValue

Источник

def transform[S](s: T => S, f: Throwable => Throwable)(implicit executor: ExecutionContext): Future[S]

Создаёт новый фьючер, применяя функцию 's' к успешному результату этого фьючера или функцию 'f' к результату с ошибкой. Если при применении 's' или 'f' возникает любое некритичное исключение, это исключение будет передано в результирующий фьючер.

Источник

def transform[S](f: Try[T] => Try[S])(implicit executor: ExecutionContext): Future[S]

Создаёт новый Future, применяя указанную функцию к результату этого Future. Если при применении 'f' возникает любое некритичное исключение, это исключение будет передано в результирующий фьючер.

Источник

def transformWith[S](f: Try[T] => Future[S])(implicit executor: ExecutionContext): Future[S]

Создает новый Future, применяя указанную функцию, которая генерирует Future, к результату этого Future. Если при применении «f» возникает любое некритическое исключение, это исключение будет передано результату будущего.

Исходный код

final def withFilter(p: T => Boolean)(implicit executor: ExecutionContext): Future[T]

Используется в for-выражениях.

Исходный код

def zip[U](that: Future[U]): Future[(T, U)]

Объединяет значения Future this и Future that, создавая новое будущее, содержащее кортеж их результатов.

Если какое-либо из входных будущих завершается ошибкой, то результирующее будущее завершается той же ошибкой, без ожидания завершения другого входного будущего.

Если при применении f возникает некритическое исключение, результирующее будущее завершается этим исключением.

Исходный код

def zipWith[U, R](that: Future[U])(f: (T, U) => R)(implicit executor: ExecutionContext): Future[R]

Объединяет значения Future this и Future that с использованием функции f, создавая новое будущее, содержащее результат.

Если какое-либо из входных будущих завершается ошибкой, то результирующее будущее завершается той же ошибкой, без ожидания завершения другого входного будущего.

Если при применении f возникает некритическое исключение, результирующее будущее завершается этим исключением.

Наследованные методы

Исходный код@throws(scala.Predef.classOf[scala.concurrent.TimeoutException]) @throws(scala.Predef.classOf[scala.InterruptedException])

def ready(atMost: Duration)(implicit permit: CanAwait): Future[T]

Ожидание состояния «завершено» этого Awaitable

Этот метод не следует вызывать напрямую; используйте Await.ready вместо этого.

Исходный код@throws(scala.Predef.classOf[scala.concurrent.TimeoutException]) @throws(scala.Predef.classOf[scala.InterruptedException])

def result(atMost: Duration)(implicit permit: CanAwait): T

Ожидание и возвращение результата (типа T) этого Awaitable

Этот метод не следует вызывать напрямую; используйте Await.result вместо этого.