scala.concurrent

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 https://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:

import scala.concurrent._

When using things like Futures, it is often required to have an implicit ExecutionContext 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:

def myMethod(myParam: MyType)(implicit ec: ExecutionContext) = …
//Or
class MyClass(myParam: MyType)(implicit ec: ExecutionContext) { … }

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.

import scala.concurrent.ExcutionContext.Implicits.global

Specifying Durations

Operations often require a duration to be specified. A duration DSL is available to make defining these easier:

import scala.concurrent.duration._
val d: Duration = 10.seconds

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:

import scala.concurrent._
import ExecutionContext.Implicits.global  // implicit execution context

val firstZebra: Future[Int] = Future {
 val words = Files.readAllLines("/etc/dictionaries-common/words").asScala
 words.indexOfSlice("zebra")
}

Avoid Blocking

Although blocking is possible in order to await results (with a mandatory timeout duration):

import scala.concurrent.duration._
Await.result(firstZebra, 10.seconds)

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:

val animalRange: Future[Int] = for {
 aardvark <- firstAardvark
 zebra <- firstZebra
} yield zebra - aardvark

animalRange.onSuccess {
 case x if x > 500000 => println("It's a long way from Aardvark to Zebra")
}

Attributes

Members list

Packages

Type members

Classlikes

object Await

Await is what is used to ensure proper handling of blocking for Awaitable instances.

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.

Attributes

Source
package.scala
Supertypes
class Object
trait Matchable
class Any
Self type
Await.type
trait Awaitable[+T]

An object that may eventually be completed with a result value of type T which may be awaited using blocking methods.

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.

Attributes

Source
Awaitable.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
trait Future[T]
object never
trait Batchable

Marker trait to indicate that a Runnable is Batchable by BatchingExecutors

Marker trait to indicate that a Runnable is Batchable by BatchingExecutors

Attributes

Source
BatchingExecutor.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
Self type
trait BlockContext

A context to be notified by scala.concurrent.blocking when a thread is about to block.

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
}

Attributes

Companion
object
Source
BlockContext.scala
Supertypes
class Object
trait Matchable
class Any
object BlockContext

Attributes

Companion
trait
Source
BlockContext.scala
Supertypes
class Object
trait Matchable
class Any
Self type
sealed trait CanAwait

This marker trait is used by Await to ensure that Awaitable.ready and Awaitable.result are not directly called by user code.

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.

Attributes

Source
package.scala
Supertypes
class Object
trait Matchable
class Any

An ExecutionContext can execute program logic asynchronously, typically but not necessarily on a thread pool.

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 define the 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.

Attributes

Companion
object
Source
ExecutionContext.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes

Contains factory methods for creating execution contexts.

Contains factory methods for creating execution contexts.

Attributes

Companion
trait
Source
ExecutionContext.scala
Supertypes
class Object
trait Matchable
class Any
Self type

An ExecutionContext that is also a Java Executor.

An ExecutionContext that is also a Java Executor.

Attributes

Source
ExecutionContext.scala
Supertypes
trait Executor
class Object
trait Matchable
class Any
Known subtypes

An ExecutionContext that is also a Java ExecutorService.

An ExecutionContext that is also a Java ExecutorService.

Attributes

Source
ExecutionContext.scala
Supertypes
trait Executor
class Object
trait Matchable
class Any
Show all
trait Future[+T] extends Awaitable[T]

A Future represents a value which may or may not be currently available, but will be available at some point, or an exception if that value could not be made available.

A Future represents a value which may or may not be currently available, but will be available at some point, or an exception if that value could not be made available.

Asynchronous computations are created by calling Future.apply, which yields instances of Future. Computations are executed using an ExecutionContext, which is usually supplied implicitly, and which is commonly backed by a thread pool.

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

Note that the global context is convenient but restricted: "fatal" exceptions are reported only by printing a stack trace, and the underlying thread pool may be shared by a mix of jobs. For any nontrivial application, see the caveats explained at ExecutionContext and also the overview linked below, which explains exception handling in depth.

Attributes

See also
Companion
object
Source
Future.scala
Supertypes
trait Awaitable[T]
class Object
trait Matchable
class Any
Known subtypes
object never
object Future

Future companion object.

Future companion object.

Attributes

Companion
trait
Source
Future.scala
Supertypes
class Object
trait Matchable
class Any
Self type
Future.type
trait Promise[T]

Promise is an object which can be completed with a value or failed with an exception.

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.

Attributes

Companion
object
Source
Promise.scala
Supertypes
class Object
trait Matchable
class Any
object Promise

Attributes

Companion
trait
Source
Promise.scala
Supertypes
class Object
trait Matchable
class Any
Self type
Promise.type

Deprecated classlikes

class Channel[A]

This class provides a simple FIFO queue of data objects, which are read by one or more reader threads.

This class provides a simple FIFO queue of data objects, which are read by one or more reader threads.

Type parameters

A

type of data exchanged

Attributes

Deprecated
[Since version 2.13.0]
Source
Channel.scala
Supertypes
class Object
trait Matchable
class Any
class DelayedLazyVal[T](f: () => T, body: => Unit)(implicit exec: ExecutionContext)

A DelayedLazyVal is a wrapper for lengthy computations which have a valid partially computed result.

A DelayedLazyVal is a wrapper for lengthy computations which have a valid partially computed result.

The first argument is a function for obtaining the result at any given point in time, and the second is the lengthy computation. Once the computation is complete, the apply method will stop recalculating it and return a fixed value from that point forward.

Value parameters

body

the computation to run to completion in another thread

f

the function to obtain the current value at any point in time

Attributes

Deprecated
[Since version 2.13.0]
Source
DelayedLazyVal.scala
Supertypes
class Object
trait Matchable
class Any

The JavaConversions object provides implicit conversions supporting interoperability between Scala and Java concurrency classes.

The JavaConversions object provides implicit conversions supporting interoperability between Scala and Java concurrency classes.

Attributes

Deprecated
true
Source
JavaConversions.scala
Supertypes
class Object
trait Matchable
class Any
Self type

Attributes

Deprecated
true
Source
Future.scala
Supertypes
trait Batchable
class Object
trait Matchable
class Any
Self type
class SyncChannel[A]

A SyncChannel allows one to exchange data synchronously between a reader and a writer thread.

A SyncChannel allows one to exchange data synchronously between a reader and a writer thread. The writer thread is blocked until the data to be written has been read by a corresponding reader thread.

Attributes

Deprecated
[Since version 2.13.0]
Source
SyncChannel.scala
Supertypes
class Object
trait Matchable
class Any
class SyncVar[A]

A class to provide safe concurrent access to a mutable cell.

A class to provide safe concurrent access to a mutable cell. All methods are synchronized.

Type parameters

A

type of the contained value

Attributes

Deprecated
[Since version 2.13.0]
Source
SyncVar.scala
Supertypes
class Object
trait Matchable
class Any

Value members

Concrete methods

final def blocking[T](body: => T): T

Used to designate a piece of code which potentially blocks, allowing the current BlockContext to adjust the runtime's behavior.

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.

Value parameters

body

A piece of code which contains potentially blocking or long running calls.

Attributes

Throws

CancellationException if the computation was cancelled

InterruptedException in the case that a wait within the blocking body was interrupted

Source
package.scala