An object that may eventually be completed with a result value of type T
which may be awaited using blocking methods.
The Await object provides methods that allow accessing the result of an Awaitable
by blocking the current thread until the Awaitable
has been completed or a timeout has occurred.
A context to be notified by scala.concurrent.blocking
when a thread is about to block. In effect this trait provides the implementation for scala.concurrent.Await
. scala.concurrent.Await.result()
and scala.concurrent.Await.ready()
locates an instance of BlockContext
by first looking for one provided through BlockContext.withBlockContext()
and failing that, checking whether Thread.currentThread
is an instance of BlockContext
. So a thread pool can have its java.lang.Thread
instances implement BlockContext
. There's a default BlockContext
used if the thread doesn't implement BlockContext
.
Typically, you'll want to chain to the previous BlockContext
, like this:
val oldContext = BlockContext.current val myContext = new BlockContext { override def blockOn[T](thunk: =>T)(implicit permission: CanAwait): T = { // you'd have code here doing whatever you need to do // when the thread is about to block. // Then you'd chain to the previous context: oldContext.blockOn(thunk) } } BlockContext.withBlockContext(myContext) { // then this block runs with myContext as the handler // for scala.concurrent.blocking }
This marker trait is used by Await to ensure that Awaitable.ready and Awaitable.result are not directly called by user code. An implicit instance of this trait is only available when user code is currently calling the methods on Await.
An ExecutionContext
can execute program logic asynchronously, typically but not necessarily on a thread pool.
A general purpose ExecutionContext
must be asynchronous in executing any Runnable
that is passed into its execute
-method. A special purpose ExecutionContext
may be synchronous but must only be passed to code that is explicitly safe to be run using a synchronously executing ExecutionContext
.
APIs such as Future.onComplete
require you to provide a callback and an implicit ExecutionContext
. The implicit ExecutionContext
will be used to execute the callback.
While it is possible to simply import scala.concurrent.ExecutionContext.Implicits.global
to obtain an implicit ExecutionContext
, application developers should carefully consider where they want to set execution policy; ideally, one place per application—or per logically related section of code— will make a decision about which ExecutionContext
to use. That is, you will mostly want to avoid hardcoding, especially via an import, scala.concurrent.ExecutionContext.Implicits.global
. The recommended approach is to add (implicit ec: ExecutionContext)
to methods, or class constructor parameters, which need an ExecutionContext
.
Then locally import a specific ExecutionContext
in one place for the entire application or module, passing it implicitly to individual methods. Alternatively define a local implicit val with the required ExecutionContext
.
A custom ExecutionContext
may be appropriate to execute code which blocks on IO or performs long-running computations. ExecutionContext.fromExecutorService
and ExecutionContext.fromExecutor
are good ways to create a custom ExecutionContext
.
The intent of ExecutionContext
is to lexically scope code execution. That is, each method, class, file, package, or application determines how to run its own code. This avoids issues such as running application callbacks on a thread pool belonging to a networking library. The size of a networking library's thread pool can be safely configured, knowing that only that library's network operations will be affected. Application callback execution can be configured separately.
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) }
Promise is an object which can be completed with a value or failed with an exception.
A promise should always eventually be completed, whether for success or failure, in order to avoid unintended resource retention for any associated Futures' callbacks or transformations.
Used to designate a piece of code which potentially blocks, allowing the current BlockContext to adjust the runtime's behavior. Properly marking blocking code may improve performance or avoid deadlocks.
Blocking on an Awaitable should be done using Await.result instead of blocking
.
A piece of code which contains potentially blocking or long running calls.
CancellationException
if the computation was cancelled
InterruptedException
in the case that a wait within the blocking body
was interrupted
Await
is what is used to ensure proper handling of blocking for Awaitable
instances.
While occasionally useful, e.g. for testing, it is recommended that you avoid Await whenever possible— instead favoring combinators and/or callbacks. Await's result
and ready
methods will block the calling thread's execution until they return, which will cause performance degradation, and possibly, deadlock issues.
© 2002-2019 EPFL, with contributions from Lightbend.
Licensed under the Apache License, Version 2.0.
https://www.scala-lang.org/api/2.13.0/scala/concurrent/index.html
This package object contains primitives for concurrent and parallel programming.
Guide
A more detailed guide to Futures and Promises, including discussion and examples can be found at http://docs.scala-lang.org/overviews/core/futures.html.
Common Imports
When working with Futures, you will often find that importing the whole concurrent package is convenient:
When using things like
Future
s, it is often required to have an implicitExecutionContext
in scope. The general advice for these implicits are as follows.If the code in question is a class or method definition, and no
ExecutionContext
is available, request one from the caller by adding an implicit parameter list:This allows the caller of the method, or creator of the instance of the class, to decide which
ExecutionContext
should be used.For typical REPL usage and experimentation, importing the global
ExecutionContext
is often desired.Specifying Durations
Operations often require a duration to be specified. A duration DSL is available to make defining these easier:
Using Futures For Non-blocking Computation
Basic use of futures is easy with the factory method on Future, which executes a provided function asynchronously, handing you back a future result of that function without blocking the current thread. In order to create the Future you will need either an implicit or explicit ExecutionContext to be provided:
Avoid Blocking
Although blocking is possible in order to await results (with a mandatory timeout duration):
and although this is sometimes necessary to do, in particular for testing purposes, blocking in general is discouraged when working with Futures and concurrency in order to avoid potential deadlocks and improve performance. Instead, use callbacks or combinators to remain in the future domain: