@@ -24,11 +24,12 @@ import scala.reflect.ClassTag
24
24
25
25
import scala .concurrent .ExecutionContext .parasitic
26
26
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,
28
28
* but will be available at some point, or an exception if that value could not be made available.
29
29
*
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.
32
33
*
33
34
* {{{
34
35
* import ExecutionContext.Implicits.global
@@ -41,6 +42,15 @@ import scala.concurrent.ExecutionContext.parasitic
41
42
* }
42
43
* }}}
43
44
*
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
+ *
44
54
* @see [[https://docs.scala-lang.org/overviews/core/futures.html Futures and Promises ]]
45
55
*
46
56
* @define multipleCallbacks
@@ -55,8 +65,7 @@ import scala.concurrent.ExecutionContext.parasitic
55
65
* - `InterruptedException` - not contained within futures
56
66
* - all `scala.util.control.ControlThrowable` except `NonLocalReturnControl` - not contained within futures
57
67
*
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.
60
69
* If a future is failed with a `scala.runtime.NonLocalReturnControl`,
61
70
* it is completed with a value from that throwable instead.
62
71
*
0 commit comments