Характеристика Future.Future

trait Future[+T] extends Awaitable[T]

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

Асинхронные вычисления, которые возвращают значения типа 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, а это означает, что будущее завершилось ошибкой. Futures, полученные через комбинаторы, имеют ту же ошибку, что и будущее, из которого они были получены. Следующие объекты throwable не содержатся в будущем: - Error - критические ошибки не содержатся в futures - InterruptedException - не содержатся в futures - все scala.util.control.ControlThrowable за исключением NonLocalReturnControl - не содержатся в futures

Вместо этого будущее завершается с 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)]

Комбинирует значения this и that будущего и создаёт новое будущее, содержащее кортеж их результатов.

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

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

Источник

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

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

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

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

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

Источник

def ready(atMost: Duration)(implicit permit: CanAwait): Awaitable.this.type

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

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

Источник

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

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

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