package 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 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:
import scala.concurrent._
When using things like Future
s, 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 source = scala.io.Source.fromFile("/etc/dictionaries-common/words") source.toSeq.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") }
- Source
- package.scala
- Alphabetic
- By Inheritance
- concurrent
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Type Members
-
trait
Awaitable[+T] extends AnyRef
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 theAwaitable
has been completed or a timeout has occurred. -
trait
BlockContext extends AnyRef
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 forscala.concurrent.Await
.scala.concurrent.Await.result()
andscala.concurrent.Await.ready()
locates an instance ofBlockContext
by first looking for one provided throughBlockContext.withBlockContext()
and failing that, checking whetherThread.currentThread
is an instance ofBlockContext
. So a thread pool can have itsjava.lang.Thread
instances implementBlockContext
. There's a defaultBlockContext
used if the thread doesn't implementBlockContext
.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 }
-
sealed
trait
CanAwait extends AnyRef
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.
- Annotations
- @implicitNotFound( msg = ... )
- type CancellationException = java.util.concurrent.CancellationException
-
class
Channel[A] extends AnyRef
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.
- A
type of data exchanged
-
class
DelayedLazyVal[T] extends AnyRef
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.- Since
2.8
-
trait
ExecutionContext extends AnyRef
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 anyRunnable
that is passed into itsexecute
-method. A special purposeExecutionContext
may be synchronous but must only be passed to code that is explicitly safe to be run using a synchronously executingExecutionContext
.APIs such as
Future.onComplete
require you to provide a callback and an implicitExecutionContext
. The implicitExecutionContext
will be used to execute the callback.While it is possible to simply import
scala.concurrent.ExecutionContext.Implicits.global
to obtain an implicitExecutionContext
, 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 whichExecutionContext
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 anExecutionContext
.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 requiredExecutionContext
.A custom
ExecutionContext
may be appropriate to execute code which blocks on IO or performs long-running computations.ExecutionContext.fromExecutorService
andExecutionContext.fromExecutor
are good ways to create a customExecutionContext
.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.- Annotations
- @implicitNotFound( msg = ... )
-
trait
ExecutionContextExecutor extends ExecutionContext with Executor
An ExecutionContext that is also a Java Executor.
-
trait
ExecutionContextExecutorService extends ExecutionContextExecutor with ExecutorService
An ExecutionContext that is also a Java ExecutorService.
- type ExecutionException = java.util.concurrent.ExecutionException
-
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.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 suppliedExecutionContext
, 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) }
- See also
-
trait
OnCompleteRunnable extends AnyRef
A marker indicating that a
java.lang.Runnable
provided toscala.concurrent.ExecutionContext
wraps a callback provided toFuture.onComplete
.A marker indicating that a
java.lang.Runnable
provided toscala.concurrent.ExecutionContext
wraps a callback provided toFuture.onComplete
. All callbacks provided to aFuture
end up going throughonComplete
, so this allows anExecutionContext
to special-case callbacks that were executed byFuture
if desired. -
trait
Promise[T] extends AnyRef
Promise is an object which can be completed with a value or failed with an exception.
-
class
SyncChannel[A] extends AnyRef
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.- Since
2.0
-
class
SyncVar[A] extends AnyRef
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.
- A
type of the contained value
- type TimeoutException = java.util.concurrent.TimeoutException
-
class
Lock extends AnyRef
This class ...
This class ...
- Annotations
- @deprecated
- Deprecated
(Since version 2.11.2) use java.util.concurrent.locks.Lock
Value Members
-
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
.- body
A piece of code which contains potentially blocking or long running calls.
- Annotations
- @throws( clazz = classOf[Exception] )
- Exceptions thrown
CancellationException
if the computation was cancelledInterruptedException
in the case that a wait within the blockingbody
was interrupted
-
object
Await
Await
is what is used to ensure proper handling of blocking forAwaitable
instances.Await
is what is used to ensure proper handling of blocking forAwaitable
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
andready
methods will block the calling thread's execution until they return, which will cause performance degradation, and possibly, deadlock issues. - object BlockContext
-
object
ExecutionContext
Contains factory methods for creating execution contexts.
-
object
Future
Future companion object.
-
object
JavaConversions
The
JavaConversions
object provides implicit conversions supporting interoperability between Scala and Java concurrency classes. - object Promise
Deprecated Value Members
-
def
future[T](body: ⇒ T)(implicit executor: ExecutionContext): Future[T]
Starts an asynchronous computation and returns a
Future
object with the result of that computation.Starts an asynchronous computation and returns a
Future
object with the result of that computation.The result becomes available once the asynchronous computation is completed.
- T
the type of the result
- body
the asynchronous computation
- executor
the execution context on which the future is run
- returns
the
Future
holding the result of the computation
- Annotations
- @deprecated
- Deprecated
(Since version 2.11.0) use
Future { ... }
instead
-
def
promise[T](): Promise[T]
Creates a promise object which can be completed with a value or an exception.
Creates a promise object which can be completed with a value or an exception.
- T
the type of the value in the promise
- returns
the newly created
Promise
object
- Annotations
- @deprecated
- Deprecated
(Since version 2.11.0) use
Promise[T]()
instead
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.collection.parallel.immutable
- Immutable, parallel data-structures such asParVector
,ParRange
,ParHashMap
orParHashSet
scala.collection.parallel.mutable
- Mutable, parallel data-structures such asParArray
,ParHashMap
,ParTrieMap
orParHashSet
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.swing
- A convenient wrapper around Java's GUI framework called Swing (scala-swing.jar)scala.util.parsing
- Parser combinators (scala-parser-combinators.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
.