trait Future[+T] extends Awaitable[T]
A Future
represents a value which may or may not *currently* be available,
but will be available at some point, or an exception if that value could not be made available.
Asynchronous computations that yield futures are created with the Future.apply
call and are computed using a supplied ExecutionContext
,
which can be backed by a Thread pool.
import ExecutionContext.Implicits.global val s = "Hello" val f: Future[String] = Future { s + " future!" } f foreach { msg => println(msg) }
- Source
- Future.scala
- See also
- Grouped
- Alphabetic
- By Inheritance
- Future
- Awaitable
- AnyRef
- Any
- by any2stringadd
- by StringFormat
- by Ensuring
- by ArrowAssoc
- Hide All
- Show All
- Public
- All
Callbacks
- abstract def onComplete[U](f: (Try[T]) => U)(implicit executor: ExecutionContext): Unit
When this future is completed, either through an exception, or a value, apply the provided function.
When this future is completed, either through an exception, or a value, apply the provided function.
If the future has already been completed, this will either be applied immediately or be scheduled asynchronously.
Note that the returned value of
f
will be discarded.Since this method executes asynchronously and does not produce a return value, any non-fatal exceptions thrown will be reported to the
ExecutionContext
.Multiple callbacks may be registered; there is no guarantee that they will be executed in a particular order.
The provided callback always runs in the provided implicit
ExecutionContext
, though there is no guarantee that theexecute()
method on theExecutionContext
will be called once per callback or thatexecute()
will be called in the current thread. That is, the implementation may run multiple callbacks in a batch within a singleexecute()
and it may runexecute()
either immediately or asynchronously. Completion of the Future must *happen-before* the invocation of the callback.- U
only used to accept any return type of the given callback function
- f
the function to be executed when this
Future
completes
- def andThen[U](pf: PartialFunction[Try[T], U])(implicit executor: ExecutionContext): Future[T]
Applies the side-effecting function to the result of this future, and returns a new future with the result of this future.
Applies the side-effecting function to the result of this future, and returns a new future with the result of this future.
This method allows one to enforce that the callbacks are executed in a specified order.
Note that if one of the chained
andThen
callbacks throws an exception, that exception is not propagated to the subsequentandThen
callbacks. Instead, the subsequentandThen
callbacks are given the original value of this future.The following example prints out
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) }
Since this method executes asynchronously and does not produce a return value, any non-fatal exceptions thrown will be reported to the
ExecutionContext
.- U
only used to accept any return type of the given
PartialFunction
- pf
a
PartialFunction
which will be conditionally applied to the outcome of thisFuture
- returns
a
Future
which will be completed with the exact same outcome as thisFuture
but after thePartialFunction
has been executed.
- def foreach[U](f: (T) => U)(implicit executor: ExecutionContext): Unit
Asynchronously processes the value in the future once the value becomes available.
Asynchronously processes the value in the future once the value becomes available.
WARNING: Will not be called if this future is never completed or if it is completed with a failure.
Since this method executes asynchronously and does not produce a return value, any non-fatal exceptions thrown will be reported to the
ExecutionContext
.- U
only used to accept any return type of the given callback function
- f
the function which will be executed if this
Future
completes with a result, the return value off
will be discarded.
Polling
- abstract def isCompleted: Boolean
Returns whether the future had already been completed with a value or an exception.
Returns whether the future had already been completed with a value or an exception.
Note: using this method yields nondeterministic dataflow programs.
- returns
true
if the future was completed,false
otherwise
- abstract def value: Option[Try[T]]
The current value of this
Future
.The current value of this
Future
.Note: using this method yields nondeterministic dataflow programs.
If the future was not completed the returned value will be
None
. If the future was completed the value will beSome(Success(t))
if it contained a valid result, orSome(Failure(error))
if it contained an exception.- returns
None
if theFuture
wasn't completed,Some
if it was.
Transformations
- abstract def transform[S](f: (Try[T]) => Try[S])(implicit executor: ExecutionContext): Future[S]
Creates a new Future by applying the specified function to the result of this Future.
Creates a new Future by applying the specified function to the result of this Future. If there is any non-fatal exception thrown when 'f' is applied then that exception will be propagated to the resulting future.
- S
the type of the returned
Future
- f
function that transforms the result of this future
- returns
a
Future
that will be completed with the transformed value
- abstract def transformWith[S](f: (Try[T]) => Future[S])(implicit executor: ExecutionContext): Future[S]
Creates a new Future by applying the specified function, which produces a Future, to the result of this Future.
Creates a new Future by applying the specified function, which produces a Future, to the result of this Future. If there is any non-fatal exception thrown when 'f' is applied then that exception will be propagated to the resulting future.
- S
the type of the returned
Future
- f
function that transforms the result of this future
- returns
a
Future
that will be completed with the transformed value
- def collect[S](pf: PartialFunction[T, S])(implicit executor: ExecutionContext): Future[S]
Creates a new future by mapping the value of the current future, if the given partial function is defined at that value.
Creates a new future by mapping the value of the current future, if the given partial function is defined at that value.
If the current future contains a value for which the partial function is defined, the new future will also hold that value. Otherwise, the resulting future will fail with a
NoSuchElementException
.If the current future fails, then the resulting future also fails.
Example:
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
- S
the type of the returned
Future
- pf
the
PartialFunction
to apply to the successful result of thisFuture
- returns
a
Future
holding the result of application of thePartialFunction
or aNoSuchElementException
- def failed: Future[Throwable]
The returned
Future
will be successfully completed with theThrowable
of the originalFuture
if the originalFuture
fails.The returned
Future
will be successfully completed with theThrowable
of the originalFuture
if the originalFuture
fails.If the original
Future
is successful, the returnedFuture
is failed with aNoSuchElementException
.This future may contain a throwable object and this means that the future failed. Futures obtained through combinators have the same exception as the future they were obtained from. The following throwable objects are not contained in the future:
Error
- fatal errors are not contained within futuresInterruptedException
- not contained within futures- all
scala.util.control.ControlThrowable
exceptNonLocalReturnControl
- not contained within futures
Instead, the future is completed with a ExecutionException with one of the exceptions above as the cause. If a future is failed with a
scala.runtime.NonLocalReturnControl
, it is completed with a value from that throwable instead.- returns
a failed projection of this
Future
.
- def fallbackTo[U >: T](that: Future[U]): Future[U]
Creates a new future which holds the result of this future if it was completed successfully, or, if not, the result of the
that
future ifthat
is completed successfully.Creates a new future which holds the result of this future if it was completed successfully, or, if not, the result of the
that
future ifthat
is completed successfully. If both futures are failed, the resulting future holds the throwable object of the first future.Using this method will not cause concurrent programs to become nondeterministic.
Example:
val f = Future { throw new RuntimeException("failed") } val g = Future { 5 } val h = f fallbackTo g h foreach println // Eventually prints 5
- U
the type of the other
Future
and the resultingFuture
- that
the
Future
whose result we want to use if thisFuture
fails.- returns
a
Future
with the successful result of this or thatFuture
or the failure of thisFuture
if both fail
- def filter(p: (T) => Boolean)(implicit executor: ExecutionContext): Future[T]
Creates a new future by filtering the value of the current future with a predicate.
Creates a new future by filtering the value of the current future with a predicate.
If the current future contains a value which satisfies the predicate, the new future will also hold that value. Otherwise, the resulting future will fail with a
NoSuchElementException
.If the current future fails, then the resulting future also fails.
Example:
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
- p
the predicate to apply to the successful result of this
Future
- returns
a
Future
which will hold the successful result of thisFuture
if it matches the predicate or aNoSuchElementException
- def flatMap[S](f: (T) => Future[S])(implicit executor: ExecutionContext): Future[S]
Creates a new future by applying a function to the successful result of this future, and returns the result of the function as the new future.
Creates a new future by applying a function to the successful result of this future, and returns the result of the function as the new future. If this future is completed with an exception then the new future will also contain this exception.
Example:
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
is translated to:
f flatMap { (x: Int) => g map { (y: Int) => x + y } }
- S
the type of the returned
Future
- f
the function which will be applied to the successful result of this
Future
- returns
a
Future
which will be completed with the result of the application of the function
- def flatten[S](implicit ev: <:<[T, Future[S]]): Future[S]
Creates a new future with one level of nesting flattened, this method is equivalent to
flatMap(identity)
.Creates a new future with one level of nesting flattened, this method is equivalent to
flatMap(identity)
.- S
the type of the returned
Future
- def map[S](f: (T) => S)(implicit executor: ExecutionContext): Future[S]
Creates a new future by applying a function to the successful result of this future.
Creates a new future by applying a function to the successful result of this future. If this future is completed with an exception then the new future will also contain this exception.
Example:
val f = Future { "The future" } val g = f map { x: String => x + " is now!" }
Note that a for comprehension involving a
Future
may expand to include a call tomap
and orflatMap
andwithFilter
. See scala.concurrent.Future#flatMap for an example of such a comprehension.- S
the type of the returned
Future
- f
the function which will be applied to the successful result of this
Future
- returns
a
Future
which will be completed with the result of the application of the function
- def mapTo[S](implicit tag: ClassTag[S]): Future[S]
Creates a new
Future[S]
which is completed with thisFuture
's result if that conforms toS
's erased type or aClassCastException
otherwise.Creates a new
Future[S]
which is completed with thisFuture
's result if that conforms toS
's erased type or aClassCastException
otherwise.- S
the type of the returned
Future
- tag
the
ClassTag
which will be used to cast the result of thisFuture
- returns
a
Future
holding the casted result of thisFuture
or aClassCastException
otherwise
- def recover[U >: T](pf: PartialFunction[Throwable, U])(implicit executor: ExecutionContext): Future[U]
Creates a new future that will handle any matching throwable that this future might contain.
Creates a new future that will handle any matching throwable that this future might contain. If there is no match, or if this future contains a valid result then the new future will contain the same.
Example:
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
- U
the type of the returned
Future
- pf
the
PartialFunction
to apply if thisFuture
fails- returns
a
Future
with the successful value of thisFuture
or the result of thePartialFunction
- def recoverWith[U >: T](pf: PartialFunction[Throwable, Future[U]])(implicit executor: ExecutionContext): Future[U]
Creates a new future that will handle any matching throwable that this future might contain by assigning it a value of another future.
Creates a new future that will handle any matching throwable that this future might contain by assigning it a value of another future.
If there is no match, or if this future contains a valid result then the new future will contain the same result.
Example:
val f = Future { Int.MaxValue } Future (6 / 0) recoverWith { case e: ArithmeticException => f } // result: Int.MaxValue
- U
the type of the returned
Future
- pf
the
PartialFunction
to apply if thisFuture
fails- returns
a
Future
with the successful value of thisFuture
or the outcome of theFuture
returned by thePartialFunction
- def transform[S](s: (T) => S, f: (Throwable) => Throwable)(implicit executor: ExecutionContext): Future[S]
Creates a new future by applying the 's' function to the successful result of this future, or the 'f' function to the failed result.
Creates a new future by applying the 's' function to the successful result of this future, or the 'f' function to the failed result. If there is any non-fatal exception thrown when 's' or 'f' is applied, that exception will be propagated to the resulting future.
- S
the type of the returned
Future
- s
function that transforms a successful result of the receiver into a successful result of the returned future
- f
function that transforms a failure of the receiver into a failure of the returned future
- returns
a
Future
that will be completed with the transformed value
- final def withFilter(p: (T) => Boolean)(implicit executor: ExecutionContext): Future[T]
Used by for-comprehensions.
- def zip[U](that: Future[U]): Future[(T, U)]
Zips the values of
this
andthat
future, and creates a new future holding the tuple of their results.Zips the values of
this
andthat
future, and creates a new future holding the tuple of their results.If
this
future fails, the resulting future is failed with the throwable stored inthis
. Otherwise, ifthat
future fails, the resulting future is failed with the throwable stored inthat
.- U
the type of the other
Future
- that
the other
Future
- returns
a
Future
with the results of both futures or the failure of the first of them that failed
- def zipWith[U, R](that: Future[U])(f: (T, U) => R)(implicit executor: ExecutionContext): Future[R]
Zips the values of
this
andthat
future using a functionf
, and creates a new future holding the result.Zips the values of
this
andthat
future using a functionf
, and creates a new future holding the result.If
this
future fails, the resulting future is failed with the throwable stored inthis
. Otherwise, ifthat
future fails, the resulting future is failed with the throwable stored inthat
. If the application off
throws a throwable, the resulting future is failed with that throwable if it is non-fatal.- U
the type of the other
Future
- R
the type of the resulting
Future
- that
the other
Future
- f
the function to apply to the results of
this
andthat
- returns
a
Future
with the result of the application off
to the results ofthis
andthat
Ungrouped
- abstract def ready(atMost: Duration)(implicit permit: CanAwait): Future.this.type
Await the "completed" state of this
Awaitable
.Await the "completed" state of this
Awaitable
.This method should not be called directly; use Await.ready instead.
- atMost
maximum wait time, which may be negative (no waiting is done), Duration.Inf for unbounded waiting, or a finite positive duration
- returns
this
Awaitable
- Definition Classes
- Awaitable
- Annotations
- @throws(classOf[TimeoutException]) @throws(classOf[InterruptedException])
- Exceptions thrown
IllegalArgumentException
ifatMost
is Duration.UndefinedInterruptedException
if the current thread is interrupted while waitingTimeoutException
if after waiting for the specified time thisAwaitable
is still not ready
- abstract def result(atMost: Duration)(implicit permit: CanAwait): T
Await and return the result (of type
T
) of thisAwaitable
.Await and return the result (of type
T
) of thisAwaitable
.This method should not be called directly; use Await.result instead.
- atMost
maximum wait time, which may be negative (no waiting is done), Duration.Inf for unbounded waiting, or a finite positive duration
- returns
the result value if the
Awaitable
is completed within the specific maximum wait time
- Definition Classes
- Awaitable
- Annotations
- @throws(classOf[Exception])
- Exceptions thrown
IllegalArgumentException
ifatMost
is Duration.UndefinedInterruptedException
if the current thread is interrupted while waitingTimeoutException
if after waiting for the specified time thisAwaitable
is still not ready
This is the documentation for the Scala standard library.
Package structure
The scala package contains core types like
Int
,Float
,Array
orOption
which are accessible in all Scala compilation units without explicit qualification or imports.Notable packages include:
scala.collection
and its sub-packages contain Scala's collections frameworkscala.collection.immutable
- Immutable, sequential data-structures such asVector
,List
,Range
,HashMap
orHashSet
scala.collection.mutable
- Mutable, sequential data-structures such asArrayBuffer
,StringBuilder
,HashMap
orHashSet
scala.collection.concurrent
- Mutable, concurrent data-structures such asTrieMap
scala.concurrent
- Primitives for concurrent programming such asFutures
andPromises
scala.io
- Input and output operationsscala.math
- Basic math functions and additional numeric types likeBigInt
andBigDecimal
scala.sys
- Interaction with other processes and the operating systemscala.util.matching
- Regular expressionsOther packages exist. See the complete list on the right.
Additional parts of the standard library are shipped as separate libraries. These include:
scala.reflect
- Scala's reflection API (scala-reflect.jar)scala.xml
- XML parsing, manipulation, and serialization (scala-xml.jar)scala.collection.parallel
- Parallel collections (scala-parallel-collections.jar)scala.util.parsing
- Parser combinators (scala-parser-combinators.jar)scala.swing
- A convenient wrapper around Java's GUI framework called Swing (scala-swing.jar)Automatic imports
Identifiers in the scala package and the
scala.Predef
object are always in scope by default.Some of these identifiers are type aliases provided as shortcuts to commonly used classes. For example,
List
is an alias forscala.collection.immutable.List
.Other aliases refer to classes provided by the underlying platform. For example, on the JVM,
String
is an alias forjava.lang.String
.