| 122 |
|
* applies across normal vs exceptional outcomes, sync vs async |
| 123 |
|
* actions, binary triggers, and various forms of completions. |
| 124 |
|
* |
| 125 |
< |
* Non-nullness of field result (set via CAS) indicates done. An |
| 126 |
< |
* AltResult is used to box null as a result, as well as to hold |
| 127 |
< |
* exceptions. Using a single field makes completion simple to |
| 128 |
< |
* detect and trigger. Encoding and decoding is straightforward |
| 129 |
< |
* but adds to the sprawl of trapping and associating exceptions |
| 130 |
< |
* with targets. Minor simplifications rely on (static) NIL (to |
| 131 |
< |
* box null results) being the only AltResult with a null |
| 132 |
< |
* exception field, so we don't usually need explicit comparisons. |
| 133 |
< |
* Even though some of the generics casts are unchecked (see |
| 134 |
< |
* SuppressWarnings annotations), they are placed to be |
| 135 |
< |
* appropriate even if checked. |
| 125 |
> |
* Non-nullness of volatile field "result" indicates done. It may |
| 126 |
> |
* be set directly if known to be thread-confined, else via CAS. |
| 127 |
> |
* An AltResult is used to box null as a result, as well as to |
| 128 |
> |
* hold exceptions. Using a single field makes completion simple |
| 129 |
> |
* to detect and trigger. Result encoding and decoding is |
| 130 |
> |
* straightforward but tedious and adds to the sprawl of trapping |
| 131 |
> |
* and associating exceptions with targets. Minor simplifications |
| 132 |
> |
* rely on (static) NIL (to box null results) being the only |
| 133 |
> |
* AltResult with a null exception field, so we don't usually need |
| 134 |
> |
* explicit comparisons. Even though some of the generics casts |
| 135 |
> |
* are unchecked (see SuppressWarnings annotations), they are |
| 136 |
> |
* placed to be appropriate even if checked. |
| 137 |
|
* |
| 138 |
|
* Dependent actions are represented by Completion objects linked |
| 139 |
|
* as Treiber stacks headed by field "stack". There are Completion |
| 140 |
< |
* classes for each kind of action, grouped into single-input |
| 141 |
< |
* (UniCompletion), two-input (BiCompletion), projected |
| 142 |
< |
* (BiCompletions using either (not both) of two inputs), shared |
| 143 |
< |
* (CoCompletion, used by the second of two sources), zero-input |
| 144 |
< |
* source actions, and Signallers that unblock waiters. Class |
| 145 |
< |
* Completion extends ForkJoinTask to enable async execution |
| 140 |
> |
* classes for each kind of action, grouped into: |
| 141 |
> |
* - single-input (UniCompletion), |
| 142 |
> |
* - two-input (BiCompletion), |
| 143 |
> |
* - projected (BiCompletions using exactly one of two inputs), |
| 144 |
> |
* - shared (CoCompletion, used by the second of two sources), |
| 145 |
> |
* - zero-input source actions, |
| 146 |
> |
* - Signallers that unblock waiters. |
| 147 |
> |
* Class Completion extends ForkJoinTask to enable async execution |
| 148 |
|
* (adding no space overhead because we exploit its "tag" methods |
| 149 |
|
* to maintain claims). It is also declared as Runnable to allow |
| 150 |
|
* usage with arbitrary executors. |
| 160 |
|
* encounter layers of adapters in common usages. |
| 161 |
|
* |
| 162 |
|
* * Boolean CompletableFuture method x(...) (for example |
| 163 |
< |
* uniApply) takes all of the arguments needed to check that an |
| 163 |
> |
* biApply) takes all of the arguments needed to check that an |
| 164 |
|
* action is triggerable, and then either runs the action or |
| 165 |
|
* arranges its async execution by executing its Completion |
| 166 |
|
* argument, if present. The method returns true if known to be |
| 175 |
|
* forms.) The claim() callback suppresses function invocation |
| 176 |
|
* if already claimed by another thread. |
| 177 |
|
* |
| 178 |
+ |
* * Some classes (for example UniApply) have separate handling |
| 179 |
+ |
* code for when known to be thread-confined ("now" methods) and |
| 180 |
+ |
* for when shared (in tryFire), for efficiency. |
| 181 |
+ |
* |
| 182 |
|
* * CompletableFuture method xStage(...) is called from a public |
| 183 |
< |
* stage method of CompletableFuture x. It screens user |
| 183 |
> |
* stage method of CompletableFuture f. It screens user |
| 184 |
|
* arguments and invokes and/or creates the stage object. If |
| 185 |
< |
* not async and x is already complete, the action is run |
| 186 |
< |
* immediately. Otherwise a Completion c is created, pushed to |
| 187 |
< |
* x's stack (unless done), and started or triggered via |
| 188 |
< |
* c.tryFire. This also covers races possible if x completes |
| 189 |
< |
* while pushing. Classes with two inputs (for example BiApply) |
| 190 |
< |
* deal with races across both while pushing actions. The |
| 191 |
< |
* second completion is a CoCompletion pointing to the first, |
| 192 |
< |
* shared so that at most one performs the action. The |
| 193 |
< |
* multiple-arity methods allOf and anyOf do this pairwise to |
| 194 |
< |
* form trees of completions. |
| 185 |
> |
* not async and already triggerable, the action is run |
| 186 |
> |
* immediately. Otherwise a Completion c is created, and |
| 187 |
> |
* submitted to the executor if triggerable, or pushed onto f's |
| 188 |
> |
* stack if not. Completion actions are started via c.tryFire. |
| 189 |
> |
* We recheck after pushing to a source future's stack to cover |
| 190 |
> |
* possible races if the source completes while pushing. |
| 191 |
> |
* Classes with two inputs (for example BiApply) deal with races |
| 192 |
> |
* across both while pushing actions. The second completion is |
| 193 |
> |
* a CoCompletion pointing to the first, shared so that at most |
| 194 |
> |
* one performs the action. The multiple-arity methods allOf |
| 195 |
> |
* and anyOf do this pairwise to form trees of completions. |
| 196 |
|
* |
| 197 |
|
* Note that the generic type parameters of methods vary according |
| 198 |
|
* to whether "this" is a source, dependent, or completion. |
