diff options
author | Lukas Rytz <lukas.rytz@typesafe.com> | 2015-02-03 12:14:18 +0100 |
---|---|---|
committer | Lukas Rytz <lukas.rytz@typesafe.com> | 2015-02-03 12:14:18 +0100 |
commit | fdb3d96409033ea0b15a37118c423618ac00acb5 (patch) | |
tree | 9da60492050d803acd77a8cee06b90788c0bbdc3 /src/library | |
parent | c52083b9332e37ccd6cc82cd43928f06a24b124f (diff) | |
parent | 207b67a10048b6eb3385187db288fbf72648907c (diff) | |
download | scala-fdb3d96409033ea0b15a37118c423618ac00acb5.tar.gz scala-fdb3d96409033ea0b15a37118c423618ac00acb5.tar.bz2 scala-fdb3d96409033ea0b15a37118c423618ac00acb5.zip |
Merge pull request #4245 from dickwall/doc/scaladoc-concurrent-package
Document concurrent package object
Diffstat (limited to 'src/library')
-rw-r--r-- | src/library/scala/concurrent/package.scala | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/src/library/scala/concurrent/package.scala b/src/library/scala/concurrent/package.scala index 4843d28679..d159dda414 100644 --- a/src/library/scala/concurrent/package.scala +++ b/src/library/scala/concurrent/package.scala @@ -12,6 +12,75 @@ import scala.concurrent.duration.Duration import scala.annotation.implicitNotFound /** 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, furthermore you are likely to need an implicit ExecutionContext + * in scope for many operations involving Futures and Promises: + * + * {{{ + * import scala.concurrent._ + * import ExecutionContext.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") + * } + * }}} */ package object concurrent { type ExecutionException = java.util.concurrent.ExecutionException @@ -70,6 +139,11 @@ package concurrent { /** * `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 + * when possible in favor of callbacks and combinators like onComplete and use in + * for comprehensions. Await will block the thread on which it runs, and could cause + * performance and deadlock issues. */ object Await { /** |