# Scala Async Project ## Quickstart - Add `scala-async.jar` to your classpath - Use Scala 2.10.0 ```scala 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 } ``` ## What is `async`? `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: ```scala 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 ``` Lines 1 defines an asynchronous method: it returns a `Future`. Line 3 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 4 begins by triggering `slowCalcFuture`, and then suspending until it has been calculating. 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 we this code is non-blocking, it is not parallel. If we wanted to parallelize the two computations, we could rearrange the code as follows. ```scala def combined: Future[Int] = async { val future1 = slowCalcFuture val future2 = slowCalcFuture await(future1) + await(future2) } ``` ## Comparison with direct use of `Future` API This computation could also be expressed by directly using the higher-order functions of Futures: ```scala 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`. 1. The code more directly reflects the programmers intent, and does not require us to name the results `r1` and `r2`. This advantage is even more pronounces when we mix control structures in `async` blocks. 2. `async` blocks are compiled to a single anonymous class, as opposed to a seperate 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. ## Comparison with CPS plugin The existing continations (CPS) plugin for Scala can also be used to provide syntactic layer like `async`. This approach has been used in Akka's [Dataflow Concurrency](http://doc.akka.io/docs/akka/snapshot/scala/dataflow.html) CPS based rewriting of asynchrous code also produces an closure for each suspension. It can also lead to type errors that are difficult to understand. ## How it works - The async macro analyses the block of code, looking for control structures and locations of await calls. It then breaks the code into 'chunks'. Each chunk contains a linear sequence of statements that concludes with branching decision, or with the registration of subsequent state handler as a 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` and `match` 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. This behaviour of this method is determined by the current state. It records the downcast result of the future in a field, and calls the `resume()` 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 the async block, if at the terminal state. - an `apply(): Unit` method that starts the computation. ## Troubleshooting - Logging of the transform can be enabled with `scalac -Dscala.async.debug=true`. - Tracing of the ANF transform: `scalac -Dscala.async.trace=true` - Debug the macro expansion by checking out the project and executing the application [`TreeInterrogation`](https://github.com/phaller/scala-async/blob/master/src/test/scala/scala/async/TreeInterrogation.scala#L59) ## Limitations - See the [neg](https://github.com/phaller/scala-async/tree/master/src/test/scala/scala/async/neg) test cases for for constructs that are not allowed in a async block - See the [issue list](https://github.com/phaller/scala-async/issues?state=open) for which of these restrictions are planned to be dropped in the next milestone. - See [#13](https://github.com/phaller/scala-async/issues/13) for why `await` is not possible in closures, and for suggestions on ways to structure the code to work around this limitation. ## Building The async macro and its test suite can be built and run with SBT. ## Contributing If you are interested in contributing code, we ask you to complete and submit to us the Scala Contributor License Agreement, which allows us to ensure that all code submitted to the project is unencumbered by copyrights or patents. The form is available at: http://www.scala-lang.org/sites/default/files/contributor_agreement.pdf Before submitting a pull-request, please make sure you have followed the guidelines outlined in our [Pull Request Policy](https://github.com/scala/scala/wiki/Pull-Request-Policy).