Note: this branch targets Scala 2.11.x, support for Scala 2.10.x has been moved to this branch.
To include scala-async in an existing project use the library published on Maven Central. For sbt projects add the following to your build definition - build.sbt or project/Build.scala:
libraryDependencies += "org.scala-lang.modules" %% "scala-async" % "0.9.6"
For Maven projects add the following to your (make sure to use the correct Scala version prefix, _2.10 or _2.11, to match your project’s Scala version):
<dependency>
<groupId>org.scala-lang.modules</groupId>
<artifactId>scala-async_2.11</artifactId>
<version>0.9.6</version>
</dependency>
Scala 2.12 support is introduced in 0.9.6-RC5.
After adding a scala-async to your classpath, write your first async
block:
import ExecutionContext.Implicits.global
import scala.async.Async.{async, await}
val future = async {
val f1 = async { ...; true }
val f2 = async { ...; 42 }
if (await(f1)) await(f2) else 0
}
async
marks a block of asynchronous code. Such a block usually contains
one or more await
calls, which marks a point at which the computation
will be suspended until the awaited Future
is complete.
By default, async
blocks operate on scala.concurrent.{Future, Promise}
.
The system can be adapted to alternative implementations of the
Future
pattern.
Consider the following example:
def slowCalcFuture: Future[Int] = ... // 01
def combined: Future[Int] = async { // 02
await(slowCalcFuture) + await(slowCalcFuture) // 03
}
val x: Int = Await.result(combined, 10.seconds) // 05
Line 1 defines an asynchronous method: it returns a Future
.
Line 2 begins an async
block. During compilation,
the contents of this block will be analyzed to identify
the await
calls, and transformed into non-blocking
code.
Control flow will immediately pass to line 5, as the
computation in the async
block is not executed
on the caller's thread.
Line 3 begins by triggering slowCalcFuture
, and then
suspending until it has been calculated. Only after it
has finished, we trigger it again, and suspend again.
Finally, we add the results and complete combined
, which
in turn will release line 5 (unless it had already timed out).
It is important to note that while lines 1-4 are non-blocking, they are not parallel. If we wanted to parallelize the two computations, we could rearrange the code as follows:
def combined: Future[Int] = async {
val future1 = slowCalcFuture
val future2 = slowCalcFuture
await(future1) + await(future2)
}
This computation could also be expressed by directly using the higher-order functions of Futures:
def slowCalcFuture: Future[Int] = ...
val future1 = slowCalcFuture
val future2 = slowCalcFuture
def combined: Future[Int] = for {
r1 <- future1
r2 <- future2
} yield r1 + r2
The async
approach has two advantages over the use of
map
and flatMap
:
- The code more directly reflects the programmer's intent,
and does not require us to name the results
r1
andr2
. This advantage is even more pronounced when we mix control structures inasync
blocks. async
blocks are compiled to a single anonymous class, as opposed to a separate anonymous class for each closure required at each generator (<-
) in the for-comprehension. This reduces the size of generated code, and can avoid boxing of intermediate results.
The existing continuations (CPS) plugin for Scala can also be used
to provide a syntactic layer like async
. This approach has been
used in Akka's Dataflow Concurrency
(now deprecated in favour of this library).
CPS-based rewriting of asynchronous code also produces a closure for each suspension. It can also lead to type errors that are difficult to understand.
- The
async
macro analyses the block of code, looking for control structures and locations ofawait
calls. It then breaks the code into 'chunks'. Each chunk contains a linear sequence of statements that concludes with a branching decision, or with the registration of a subsequent state handler as the continuation. - Before this analysis and transformation, the program is normalized
into a form amenable to this manipulation. This is called the
"A Normal Form" (ANF), and roughly means that:
if
andmatch
constructs are only used as statements; they cannot be used as an expression.- calls to
await
are not allowed in compound expressions.
- Identify vals, vars and defs that are accessed from multiple states. These will be lifted out to fields in the state machine object.
- Synthesize a class that holds:
- an integer representing the current state ID.
- the lifted definitions.
- an
apply(value: Try[Any]): Unit
method that will be called on completion of each future. The behavior of this method is determined by the current state. It records the downcast result of the future in a field, and calls theresume()
method. - the
resume(): Unit
method that switches on the current state and runs the users code for one 'chunk', and either: a) registers the state machine as the handler for the next future b) completes the result Promise of theasync
block, if at the terminal state. - an
apply(): Unit
method that starts the computation.
- See the neg test cases
for constructs that are not allowed in an
async
block. - See the issue list for which of these restrictions are planned to be dropped in the future.
- See #13 for why
await
is not possible in closures, and for suggestions on ways to structure the code to work around this limitation.