Skip to content

Commit e932f9c

Browse files
committed
Add caveat for global context to Future
1 parent 4ae695b commit e932f9c

File tree

1 file changed

+14
-5
lines changed

1 file changed

+14
-5
lines changed

library/src/scala/concurrent/Future.scala

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,12 @@ import scala.reflect.ClassTag
2424

2525
import scala.concurrent.ExecutionContext.parasitic
2626

27-
/** A `Future` represents a value which may or may not *currently* be available,
27+
/** A `Future` represents a value which may or may not be currently available,
2828
* but will be available at some point, or an exception if that value could not be made available.
2929
*
30-
* Asynchronous computations that yield futures are created with the `Future.apply` call and are computed using a supplied `ExecutionContext`,
31-
* which can be backed by a Thread pool.
30+
* Asynchronous computations are created by calling `Future.apply`, which yields instances of `Future`.
31+
* Computations are executed using an `ExecutionContext`, which is usually supplied implicitly,
32+
* and which is commonly backed by a thread pool.
3233
*
3334
* {{{
3435
* import ExecutionContext.Implicits.global
@@ -41,6 +42,15 @@ import scala.concurrent.ExecutionContext.parasitic
4142
* }
4243
* }}}
4344
*
45+
* Note that the `global` context is convenient but restricted:
46+
* "fatal" exceptions are reported only by printing a stack trace,
47+
* and the underlying thread pool may be shared by a mix of jobs.
48+
* For any nontrivial application, see the caveats explained at [[ExecutionContext]]
49+
* and also the overview linked below, which explains
50+
* [[https://docs.scala-lang.org/overviews/core/futures.html#exceptions exception handling]]
51+
* in depth.
52+
*
53+
*
4454
* @see [[https://docs.scala-lang.org/overviews/core/futures.html Futures and Promises]]
4555
*
4656
* @define multipleCallbacks
@@ -55,8 +65,7 @@ import scala.concurrent.ExecutionContext.parasitic
5565
* - `InterruptedException` - not contained within futures
5666
* - all `scala.util.control.ControlThrowable` except `NonLocalReturnControl` - not contained within futures
5767
*
58-
* Instead, the future is completed with a ExecutionException with one of the exceptions above
59-
* as the cause.
68+
* Instead, the future is completed with an ExecutionException that has one of the exceptions above as its cause.
6069
* If a future is failed with a `scala.runtime.NonLocalReturnControl`,
6170
* it is completed with a value from that throwable instead.
6271
*

0 commit comments

Comments
 (0)