hunt.concurrency.CompletionStage source code

1 /*
2  * Hunt - A refined core library for D programming language.
3  *
4  * Copyright (C) 2018-2019 HuntLabs
5  *
6  * Website: https://www.huntlabs.net/
7  *
8  * Licensed under the Apache-2.0 License.
9  *
10  */
11 
12 module hunt.concurrency.CompletionStage;
13 
14 // import hunt.Object;
15 // import hunt.Functions;
16 // import hunt.util.Common;
17 // import hunt.util.Runnable;
18 
19 
20 // /**
21 //  * A stage of a possibly asynchronous computation, that performs an
22 //  * action or computes a value when another CompletionStage completes.
23 //  * A stage completes upon termination of its computation, but this may
24 //  * in turn trigger other dependent stages.  The functionality defined
25 //  * in this interface takes only a few basic forms, which expand out to
26 //  * a larger set of methods to capture a range of usage styles:
27 //  *
28 //  * <ul>
29 //  *
30 //  * <li>The computation performed by a stage may be expressed as a
31 //  * Function, Consumer, or Runnable (using methods with names including
32 //  * <em>apply</em>, <em>accept</em>, or <em>run</em>, respectively)
33 //  * depending on whether it requires arguments and/or produces results.
34 //  * For example:
35 //  * <pre> {@code
36 //  * stage.thenApply(x -> square(x))
37 //  *      .thenAccept(x -> System.out.print(x))
38 //  *      .thenRun(() -> System.out.println());}</pre>
39 //  *
40 //  * An additional form (<em>compose</em>) allows the construction of
41 //  * computation pipelines from functions returning completion stages.
42 //  *
43 //  * <p>Any argument to a stage's computation is the outcome of a
44 //  * triggering stage's computation.
45 //  *
46 //  * <li>One stage's execution may be triggered by completion of a
47 //  * single stage, or both of two stages, or either of two stages.
48 //  * Dependencies on a single stage are arranged using methods with
49 //  * prefix <em>then</em>. Those triggered by completion of
50 //  * <em>both</em> of two stages may <em>combine</em> their results or
51 //  * effects, using correspondingly named methods. Those triggered by
52 //  * <em>either</em> of two stages make no guarantees about which of the
53 //  * results or effects are used for the dependent stage's computation.
54 //  *
55 //  * <li>Dependencies among stages control the triggering of
56 //  * computations, but do not otherwise guarantee any particular
57 //  * ordering. Additionally, execution of a new stage's computations may
58 //  * be arranged in any of three ways: default execution, default
59 //  * asynchronous execution (using methods with suffix <em>async</em>
60 //  * that employ the stage's default asynchronous execution facility),
61 //  * or custom (via a supplied {@link Executor}).  The execution
62 //  * properties of default and async modes are specified by
63 //  * CompletionStage implementations, not this interface. Methods with
64 //  * explicit Executor arguments may have arbitrary execution
65 //  * properties, and might not even support concurrent execution, but
66 //  * are arranged for processing in a way that accommodates asynchrony.
67 //  *
68 //  * <li>Two method forms ({@link #handle handle} and {@link
69 //  * #whenComplete whenComplete}) support unconditional computation
70 //  * whether the triggering stage completed normally or exceptionally.
71 //  * Method {@link #exceptionally exceptionally} supports computation
72 //  * only when the triggering stage completes exceptionally, computing a
73 //  * replacement result, similarly to the java {@code catch} keyword.
74 //  * In all other cases, if a stage's computation terminates abruptly
75 //  * with an (unchecked) exception or error, then all dependent stages
76 //  * requiring its completion complete exceptionally as well, with a
77 //  * {@link CompletionException} holding the exception as its cause.  If
78 //  * a stage is dependent on <em>both</em> of two stages, and both
79 //  * complete exceptionally, then the CompletionException may correspond
80 //  * to either one of these exceptions.  If a stage is dependent on
81 //  * <em>either</em> of two others, and only one of them completes
82 //  * exceptionally, no guarantees are made about whether the dependent
83 //  * stage completes normally or exceptionally. In the case of method
84 //  * {@code whenComplete}, when the supplied action itself encounters an
85 //  * exception, then the stage completes exceptionally with this
86 //  * exception unless the source stage also completed exceptionally, in
87 //  * which case the exceptional completion from the source stage is
88 //  * given preference and propagated to the dependent stage.
89 //  *
90 //  * </ul>
91 //  *
92 //  * <p>All methods adhere to the above triggering, execution, and
93 //  * exceptional completion specifications (which are not repeated in
94 //  * individual method specifications). Additionally, while arguments
95 //  * used to pass a completion result (that is, for parameters of type
96 //  * {@code T}) for methods accepting them may be null, passing a null
97 //  * value for any other parameter will result in a {@link
98 //  * NullPointerException} being thrown.
99 //  *
100 //  * <p>Method form {@link #handle handle} is the most general way of
101 //  * creating a continuation stage, unconditionally performing a
102 //  * computation that is given both the result and exception (if any) of
103 //  * the triggering CompletionStage, and computing an arbitrary result.
104 //  * Method {@link #whenComplete whenComplete} is similar, but preserves
105 //  * the result of the triggering stage instead of computing a new one.
106 //  * Because a stage's normal result may be {@code null}, both methods
107 //  * should have a computation structured thus:
108 //  *
109 //  * <pre>{@code (result, exception) -> {
110 //  *   if (exception is null) {
111 //  *     // triggering stage completed normally
112 //  *   } else {
113 //  *     // triggering stage completed exceptionally
114 //  *   }
115 //  * }}</pre>
116 //  *
117 //  * <p>This interface does not define methods for initially creating,
118 //  * forcibly completing normally or exceptionally, probing completion
119 //  * status or results, or awaiting completion of a stage.
120 //  * Implementations of CompletionStage may provide means of achieving
121 //  * such effects, as appropriate.  Method {@link #toCompletableFuture}
122 //  * enables interoperability among different implementations of this
123 //  * interface by providing a common conversion type.
124 //  *
125 //  * @author Doug Lea
126 //  */
127 // interface CompletionStage(T) {
128 
129 //     /**
130 //      * Returns a new CompletionStage that, when this stage completes
131 //      * normally, is executed with this stage's result as the argument
132 //      * to the supplied function.
133 //      *
134 //      * <p>This method is analogous to
135 //      * {@link java.util.Optional#map Optional.map} and
136 //      * {@link java.util.stream.Stream#map Stream.map}.
137 //      *
138 //      * <p>See the {@link CompletionStage} documentation for rules
139 //      * covering exceptional completion.
140 //      *
141 //      * @param fn the function to use to compute the value of the
142 //      * returned CompletionStage
143 //      * @param (U) the function's return type
144 //      * @return the new CompletionStage
145 //      */
146 //     CompletionStage!(U) thenApply(U)(Function!(T, U) fn);
147 
148 //     /**
149 //      * Returns a new CompletionStage that, when this stage completes
150 //      * normally, is executed using this stage's default asynchronous
151 //      * execution facility, with this stage's result as the argument to
152 //      * the supplied function.
153 //      *
154 //      * See the {@link CompletionStage} documentation for rules
155 //      * covering exceptional completion.
156 //      *
157 //      * @param fn the function to use to compute the value of the
158 //      * returned CompletionStage
159 //      * @param (U) the function's return type
160 //      * @return the new CompletionStage
161 //      */
162 //     CompletionStage!(U) thenApplyAsync(U)(Function!(T, U) fn);
163 
164 //     /**
165 //      * Returns a new CompletionStage that, when this stage completes
166 //      * normally, is executed using the supplied Executor, with this
167 //      * stage's result as the argument to the supplied function.
168 //      *
169 //      * See the {@link CompletionStage} documentation for rules
170 //      * covering exceptional completion.
171 //      *
172 //      * @param fn the function to use to compute the value of the
173 //      * returned CompletionStage
174 //      * @param executor the executor to use for asynchronous execution
175 //      * @param (U) the function's return type
176 //      * @return the new CompletionStage
177 //      */
178 // //     CompletionStage!(U) thenApplyAsync(U)(Function!(T, U) fn,
179 // //          Executor executor);
180 
181 // static if(is(T == void)) {
182 
183 //     CompletionStage!(void) thenAccept(Action action);
184 //     CompletionStage!(void) thenAcceptAsync(Action action);
185 //     CompletionStage!(void) thenAcceptAsync(Action action,
186 //                                                  Executor executor);
187 // } else {
188 //     /**
189 //      * Returns a new CompletionStage that, when this stage completes
190 //      * normally, is executed with this stage's result as the argument
191 //      * to the supplied action.
192 //      *
193 //      * See the {@link CompletionStage} documentation for rules
194 //      * covering exceptional completion.
195 //      *
196 //      * @param action the action to perform before completing the
197 //      * returned CompletionStage
198 //      * @return the new CompletionStage
199 //      */
200 //     CompletionStage!(void) thenAccept(Consumer!(T) action);
201 
202 //     /**
203 //      * Returns a new CompletionStage that, when this stage completes
204 //      * normally, is executed using this stage's default asynchronous
205 //      * execution facility, with this stage's result as the argument to
206 //      * the supplied action.
207 //      *
208 //      * See the {@link CompletionStage} documentation for rules
209 //      * covering exceptional completion.
210 //      *
211 //      * @param action the action to perform before completing the
212 //      * returned CompletionStage
213 //      * @return the new CompletionStage
214 //      */
215 //     CompletionStage!(void) thenAcceptAsync(Consumer!(T) action);
216 
217 //     /**
218 //      * Returns a new CompletionStage that, when this stage completes
219 //      * normally, is executed using the supplied Executor, with this
220 //      * stage's result as the argument to the supplied action.
221 //      *
222 //      * See the {@link CompletionStage} documentation for rules
223 //      * covering exceptional completion.
224 //      *
225 //      * @param action the action to perform before completing the
226 //      * returned CompletionStage
227 //      * @param executor the executor to use for asynchronous execution
228 //      * @return the new CompletionStage
229 //      */
230 //     CompletionStage!(void) thenAcceptAsync(Consumer!(T) action,
231 //                                                  Executor executor);
232 
233      
234 // }                                                 
235 //     /**
236 //      * Returns a new CompletionStage that, when this stage completes
237 //      * normally, executes the given action.
238 //      *
239 //      * See the {@link CompletionStage} documentation for rules
240 //      * covering exceptional completion.
241 //      *
242 //      * @param action the action to perform before completing the
243 //      * returned CompletionStage
244 //      * @return the new CompletionStage
245 //      */
246 //     CompletionStage!(void) thenRun(Runnable action);
247 
248 //     /**
249 //      * Returns a new CompletionStage that, when this stage completes
250 //      * normally, executes the given action using this stage's default
251 //      * asynchronous execution facility.
252 //      *
253 //      * See the {@link CompletionStage} documentation for rules
254 //      * covering exceptional completion.
255 //      *
256 //      * @param action the action to perform before completing the
257 //      * returned CompletionStage
258 //      * @return the new CompletionStage
259 //      */
260 //     CompletionStage!(void) thenRunAsync(Runnable action);
261 
262 //     /**
263 //      * Returns a new CompletionStage that, when this stage completes
264 //      * normally, executes the given action using the supplied Executor.
265 //      *
266 //      * See the {@link CompletionStage} documentation for rules
267 //      * covering exceptional completion.
268 //      *
269 //      * @param action the action to perform before completing the
270 //      * returned CompletionStage
271 //      * @param executor the executor to use for asynchronous execution
272 //      * @return the new CompletionStage
273 //      */
274 //     CompletionStage!(void) thenRunAsync(Runnable action,
275 //                                               Executor executor);
276 
277 //     /**
278 //      * Returns a new CompletionStage that, when this and the other
279 //      * given stage both complete normally, is executed with the two
280 //      * results as arguments to the supplied function.
281 //      *
282 //      * See the {@link CompletionStage} documentation for rules
283 //      * covering exceptional completion.
284 //      *
285 //      * @param other the other CompletionStage
286 //      * @param fn the function to use to compute the value of the
287 //      * returned CompletionStage
288 //      * @param (U) the type of the other CompletionStage's result
289 //      * @param (V) the function's return type
290 //      * @return the new CompletionStage
291 //      */
292 // //     CompletionStage!(V) thenCombine(U,V)(CompletionStage!(U) other,
293 // //          BiFunction!(T, U, V) fn);
294 
295 //     /**
296 //      * Returns a new CompletionStage that, when this and the other
297 //      * given stage both complete normally, is executed using this
298 //      * stage's default asynchronous execution facility, with the two
299 //      * results as arguments to the supplied function.
300 //      *
301 //      * See the {@link CompletionStage} documentation for rules
302 //      * covering exceptional completion.
303 //      *
304 //      * @param other the other CompletionStage
305 //      * @param fn the function to use to compute the value of the
306 //      * returned CompletionStage
307 //      * @param (U) the type of the other CompletionStage's result
308 //      * @param (V) the function's return type
309 //      * @return the new CompletionStage
310 //      */
311 // //     CompletionStage!(V) thenCombineAsync(U,V)(CompletionStage!(U) other,
312 // //          BiFunction!(T, U, V) fn);
313 
314 //     /**
315 //      * Returns a new CompletionStage that, when this and the other
316 //      * given stage both complete normally, is executed using the
317 //      * supplied executor, with the two results as arguments to the
318 //      * supplied function.
319 //      *
320 //      * See the {@link CompletionStage} documentation for rules
321 //      * covering exceptional completion.
322 //      *
323 //      * @param other the other CompletionStage
324 //      * @param fn the function to use to compute the value of the
325 //      * returned CompletionStage
326 //      * @param executor the executor to use for asynchronous execution
327 //      * @param (U) the type of the other CompletionStage's result
328 //      * @param (V) the function's return type
329 //      * @return the new CompletionStage
330 //      */
331 // //     CompletionStage!(V) thenCombineAsync(U,V)(CompletionStage!(U) other,
332 // //          BiFunction!(T, U, V) fn, Executor executor);
333 
334 //     /**
335 //      * Returns a new CompletionStage that, when this and the other
336 //      * given stage both complete normally, is executed with the two
337 //      * results as arguments to the supplied action.
338 //      *
339 //      * See the {@link CompletionStage} documentation for rules
340 //      * covering exceptional completion.
341 //      *
342 //      * @param other the other CompletionStage
343 //      * @param action the action to perform before completing the
344 //      * returned CompletionStage
345 //      * @param (U) the type of the other CompletionStage's result
346 //      * @return the new CompletionStage
347 //      */
348 // //     CompletionStage!(void) thenAcceptBoth(U)(CompletionStage!(U) other,
349 // //          BiConsumer!(T, U) action);
350 
351 //     /**
352 //      * Returns a new CompletionStage that, when this and the other
353 //      * given stage both complete normally, is executed using this
354 //      * stage's default asynchronous execution facility, with the two
355 //      * results as arguments to the supplied action.
356 //      *
357 //      * See the {@link CompletionStage} documentation for rules
358 //      * covering exceptional completion.
359 //      *
360 //      * @param other the other CompletionStage
361 //      * @param action the action to perform before completing the
362 //      * returned CompletionStage
363 //      * @param (U) the type of the other CompletionStage's result
364 //      * @return the new CompletionStage
365 //      */
366 // //     CompletionStage!(void) thenAcceptBothAsync(U)(CompletionStage!(U) other,
367 // //          BiConsumer!(T, U) action);
368 
369 //     /**
370 //      * Returns a new CompletionStage that, when this and the other
371 //      * given stage both complete normally, is executed using the
372 //      * supplied executor, with the two results as arguments to the
373 //      * supplied action.
374 //      *
375 //      * See the {@link CompletionStage} documentation for rules
376 //      * covering exceptional completion.
377 //      *
378 //      * @param other the other CompletionStage
379 //      * @param action the action to perform before completing the
380 //      * returned CompletionStage
381 //      * @param executor the executor to use for asynchronous execution
382 //      * @param (U) the type of the other CompletionStage's result
383 //      * @return the new CompletionStage
384 //      */
385 // //     CompletionStage!(void) thenAcceptBothAsync(U)(CompletionStage!(U) other,
386 // //          BiConsumer!(T, U) action, Executor executor);
387 
388 //     /**
389 //      * Returns a new CompletionStage that, when this and the other
390 //      * given stage both complete normally, executes the given action.
391 //      *
392 //      * See the {@link CompletionStage} documentation for rules
393 //      * covering exceptional completion.
394 //      *
395 //      * @param other the other CompletionStage
396 //      * @param action the action to perform before completing the
397 //      * returned CompletionStage
398 //      * @return the new CompletionStage
399 //      */
400 // //     CompletionStage!(void) runAfterBoth(U)(CompletionStage!(U) other,
401 // //                                               Runnable action);
402 //     /**
403 //      * Returns a new CompletionStage that, when this and the other
404 //      * given stage both complete normally, executes the given action
405 //      * using this stage's default asynchronous execution facility.
406 //      *
407 //      * See the {@link CompletionStage} documentation for rules
408 //      * covering exceptional completion.
409 //      *
410 //      * @param other the other CompletionStage
411 //      * @param action the action to perform before completing the
412 //      * returned CompletionStage
413 //      * @return the new CompletionStage
414 //      */
415 // //     CompletionStage!(void) runAfterBothAsync(U)(CompletionStage!(U) other,
416 // //                                                    Runnable action);
417 
418 //     /**
419 //      * Returns a new CompletionStage that, when this and the other
420 //      * given stage both complete normally, executes the given action
421 //      * using the supplied executor.
422 //      *
423 //      * See the {@link CompletionStage} documentation for rules
424 //      * covering exceptional completion.
425 //      *
426 //      * @param other the other CompletionStage
427 //      * @param action the action to perform before completing the
428 //      * returned CompletionStage
429 //      * @param executor the executor to use for asynchronous execution
430 //      * @return the new CompletionStage
431 //      */
432 // //     CompletionStage!(void) runAfterBothAsync(U)(CompletionStage!(U) other,
433 // //                                                    Runnable action,
434 // //                                                    Executor executor);
435 //     /**
436 //      * Returns a new CompletionStage that, when either this or the
437 //      * other given stage complete normally, is executed with the
438 //      * corresponding result as argument to the supplied function.
439 //      *
440 //      * See the {@link CompletionStage} documentation for rules
441 //      * covering exceptional completion.
442 //      *
443 //      * @param other the other CompletionStage
444 //      * @param fn the function to use to compute the value of the
445 //      * returned CompletionStage
446 //      * @param (U) the function's return type
447 //      * @return the new CompletionStage
448 //      */
449 // //     CompletionStage!(U) applyToEither(U)(CompletionStage!(T) other,
450 // //          Function!(T, U) fn);
451 
452 //     /**
453 //      * Returns a new CompletionStage that, when either this or the
454 //      * other given stage complete normally, is executed using this
455 //      * stage's default asynchronous execution facility, with the
456 //      * corresponding result as argument to the supplied function.
457 //      *
458 //      * See the {@link CompletionStage} documentation for rules
459 //      * covering exceptional completion.
460 //      *
461 //      * @param other the other CompletionStage
462 //      * @param fn the function to use to compute the value of the
463 //      * returned CompletionStage
464 //      * @param (U) the function's return type
465 //      * @return the new CompletionStage
466 //      */
467 // //     CompletionStage!(U) applyToEitherAsync(U)(CompletionStage!(T) other,
468 // //          Function!(T, U) fn);
469 
470 //     /**
471 //      * Returns a new CompletionStage that, when either this or the
472 //      * other given stage complete normally, is executed using the
473 //      * supplied executor, with the corresponding result as argument to
474 //      * the supplied function.
475 //      *
476 //      * See the {@link CompletionStage} documentation for rules
477 //      * covering exceptional completion.
478 //      *
479 //      * @param other the other CompletionStage
480 //      * @param fn the function to use to compute the value of the
481 //      * returned CompletionStage
482 //      * @param executor the executor to use for asynchronous execution
483 //      * @param (U) the function's return type
484 //      * @return the new CompletionStage
485 //      */
486 // //     CompletionStage!(U) applyToEitherAsync(U)(CompletionStage!(T) other,
487 // //          Function!(T, U) fn, Executor executor);
488 
489 // static if(is(T == void)) {
490 //     CompletionStage!(void) acceptEither(CompletionStage!(T) other,
491 //          Action action);
492 //     CompletionStage!(void) acceptEitherAsync(CompletionStage!(T) other,
493 //          Action action);
494 //     CompletionStage!(void) acceptEitherAsync(CompletionStage!(T) other,
495 //          Action action, Executor executor);
496 // } else {
497 //     /**
498 //      * Returns a new CompletionStage that, when either this or the
499 //      * other given stage complete normally, is executed with the
500 //      * corresponding result as argument to the supplied action.
501 //      *
502 //      * See the {@link CompletionStage} documentation for rules
503 //      * covering exceptional completion.
504 //      *
505 //      * @param other the other CompletionStage
506 //      * @param action the action to perform before completing the
507 //      * returned CompletionStage
508 //      * @return the new CompletionStage
509 //      */
510 //     CompletionStage!(void) acceptEither(CompletionStage!(T) other,
511 //          Consumer!(T) action);
512 
513 //     /**
514 //      * Returns a new CompletionStage that, when either this or the
515 //      * other given stage complete normally, is executed using this
516 //      * stage's default asynchronous execution facility, with the
517 //      * corresponding result as argument to the supplied action.
518 //      *
519 //      * See the {@link CompletionStage} documentation for rules
520 //      * covering exceptional completion.
521 //      *
522 //      * @param other the other CompletionStage
523 //      * @param action the action to perform before completing the
524 //      * returned CompletionStage
525 //      * @return the new CompletionStage
526 //      */
527 //     CompletionStage!(void) acceptEitherAsync(CompletionStage!(T) other,
528 //          Consumer!(T) action);
529 
530 //     /**
531 //      * Returns a new CompletionStage that, when either this or the
532 //      * other given stage complete normally, is executed using the
533 //      * supplied executor, with the corresponding result as argument to
534 //      * the supplied action.
535 //      *
536 //      * See the {@link CompletionStage} documentation for rules
537 //      * covering exceptional completion.
538 //      *
539 //      * @param other the other CompletionStage
540 //      * @param action the action to perform before completing the
541 //      * returned CompletionStage
542 //      * @param executor the executor to use for asynchronous execution
543 //      * @return the new CompletionStage
544 //      */
545 //     CompletionStage!(void) acceptEitherAsync(CompletionStage!(T) other,
546 //          Consumer!(T) action, Executor executor);
547      
548 // }
549 //     /**
550 //      * Returns a new CompletionStage that, when either this or the
551 //      * other given stage complete normally, executes the given action.
552 //      *
553 //      * See the {@link CompletionStage} documentation for rules
554 //      * covering exceptional completion.
555 //      *
556 //      * @param other the other CompletionStage
557 //      * @param action the action to perform before completing the
558 //      * returned CompletionStage
559 //      * @return the new CompletionStage
560 //      */
561 // //     CompletionStage!(void) runAfterEither(U)(CompletionStage!(U) other,
562 // //                                                 Runnable action);
563 
564 //     /**
565 //      * Returns a new CompletionStage that, when either this or the
566 //      * other given stage complete normally, executes the given action
567 //      * using this stage's default asynchronous execution facility.
568 //      *
569 //      * See the {@link CompletionStage} documentation for rules
570 //      * covering exceptional completion.
571 //      *
572 //      * @param other the other CompletionStage
573 //      * @param action the action to perform before completing the
574 //      * returned CompletionStage
575 //      * @return the new CompletionStage
576 //      */
577 // //     CompletionStage!(void) runAfterEitherAsync(U)(CompletionStage!(U) other,
578 // //          Runnable action);
579 
580 //     /**
581 //      * Returns a new CompletionStage that, when either this or the
582 //      * other given stage complete normally, executes the given action
583 //      * using the supplied executor.
584 //      *
585 //      * See the {@link CompletionStage} documentation for rules
586 //      * covering exceptional completion.
587 //      *
588 //      * @param other the other CompletionStage
589 //      * @param action the action to perform before completing the
590 //      * returned CompletionStage
591 //      * @param executor the executor to use for asynchronous execution
592 //      * @return the new CompletionStage
593 //      */
594 // //     CompletionStage!(void) runAfterEitherAsync(U)(CompletionStage!(U) other,
595 // //          Runnable action, Executor executor);
596 
597 //     /**
598 //      * Returns a new CompletionStage that is completed with the same
599 //      * value as the CompletionStage returned by the given function.
600 //      *
601 //      * <p>When this stage completes normally, the given function is
602 //      * invoked with this stage's result as the argument, returning
603 //      * another CompletionStage.  When that stage completes normally,
604 //      * the CompletionStage returned by this method is completed with
605 //      * the same value.
606 //      *
607 //      * <p>To ensure progress, the supplied function must arrange
608 //      * eventual completion of its result.
609 //      *
610 //      * <p>This method is analogous to
611 //      * {@link java.util.Optional#flatMap Optional.flatMap} and
612 //      * {@link java.util.stream.Stream#flatMap Stream.flatMap}.
613 //      *
614 //      * <p>See the {@link CompletionStage} documentation for rules
615 //      * covering exceptional completion.
616 //      *
617 //      * @param fn the function to use to compute another CompletionStage
618 //      * @param (U) the type of the returned CompletionStage's result
619 //      * @return the new CompletionStage
620 //      */
621 // //     CompletionStage!(U) thenCompose(U)(Function!(T, CompletionStage!(U)) fn);
622 
623 //     /**
624 //      * Returns a new CompletionStage that is completed with the same
625 //      * value as the CompletionStage returned by the given function,
626 //      * executed using this stage's default asynchronous execution
627 //      * facility.
628 //      *
629 //      * <p>When this stage completes normally, the given function is
630 //      * invoked with this stage's result as the argument, returning
631 //      * another CompletionStage.  When that stage completes normally,
632 //      * the CompletionStage returned by this method is completed with
633 //      * the same value.
634 //      *
635 //      * <p>To ensure progress, the supplied function must arrange
636 //      * eventual completion of its result.
637 //      *
638 //      * <p>See the {@link CompletionStage} documentation for rules
639 //      * covering exceptional completion.
640 //      *
641 //      * @param fn the function to use to compute another CompletionStage
642 //      * @param (U) the type of the returned CompletionStage's result
643 //      * @return the new CompletionStage
644 //      */
645 // //     CompletionStage!(U) thenComposeAsync(U)(Function!(T, CompletionStage!(U)) fn);
646 
647 //     /**
648 //      * Returns a new CompletionStage that is completed with the same
649 //      * value as the CompletionStage returned by the given function,
650 //      * executed using the supplied Executor.
651 //      *
652 //      * <p>When this stage completes normally, the given function is
653 //      * invoked with this stage's result as the argument, returning
654 //      * another CompletionStage.  When that stage completes normally,
655 //      * the CompletionStage returned by this method is completed with
656 //      * the same value.
657 //      *
658 //      * <p>To ensure progress, the supplied function must arrange
659 //      * eventual completion of its result.
660 //      *
661 //      * <p>See the {@link CompletionStage} documentation for rules
662 //      * covering exceptional completion.
663 //      *
664 //      * @param fn the function to use to compute another CompletionStage
665 //      * @param executor the executor to use for asynchronous execution
666 //      * @param (U) the type of the returned CompletionStage's result
667 //      * @return the new CompletionStage
668 //      */
669 // //     CompletionStage!(U) thenComposeAsync(U)
670 // //         (Function!(T, CompletionStage!(U)) fn, Executor executor);
671 
672 //     /**
673 //      * Returns a new CompletionStage that, when this stage completes
674 //      * either normally or exceptionally, is executed with this stage's
675 //      * result and exception as arguments to the supplied function.
676 //      *
677 //      * <p>When this stage is complete, the given function is invoked
678 //      * with the result (or {@code null} if none) and the exception (or
679 //      * {@code null} if none) of this stage as arguments, and the
680 //      * function's result is used to complete the returned stage.
681 //      *
682 //      * @param fn the function to use to compute the value of the
683 //      * returned CompletionStage
684 //      * @param (U) the function's return type
685 //      * @return the new CompletionStage
686 //      */
687 // //     CompletionStage!(U) handle(U)(BiFunction!(T, Throwable, U) fn);
688 
689 //     /**
690 //      * Returns a new CompletionStage that, when this stage completes
691 //      * either normally or exceptionally, is executed using this stage's
692 //      * default asynchronous execution facility, with this stage's
693 //      * result and exception as arguments to the supplied function.
694 //      *
695 //      * <p>When this stage is complete, the given function is invoked
696 //      * with the result (or {@code null} if none) and the exception (or
697 //      * {@code null} if none) of this stage as arguments, and the
698 //      * function's result is used to complete the returned stage.
699 //      *
700 //      * @param fn the function to use to compute the value of the
701 //      * returned CompletionStage
702 //      * @param (U) the function's return type
703 //      * @return the new CompletionStage
704 //      */
705 // //     CompletionStage!(U) handleAsync(U)(BiFunction!(T, Throwable, U) fn);
706 
707 //     /**
708 //      * Returns a new CompletionStage that, when this stage completes
709 //      * either normally or exceptionally, is executed using the
710 //      * supplied executor, with this stage's result and exception as
711 //      * arguments to the supplied function.
712 //      *
713 //      * <p>When this stage is complete, the given function is invoked
714 //      * with the result (or {@code null} if none) and the exception (or
715 //      * {@code null} if none) of this stage as arguments, and the
716 //      * function's result is used to complete the returned stage.
717 //      *
718 //      * @param fn the function to use to compute the value of the
719 //      * returned CompletionStage
720 //      * @param executor the executor to use for asynchronous execution
721 //      * @param (U) the function's return type
722 //      * @return the new CompletionStage
723 //      */
724 // //     CompletionStage!(U) handleAsync(U)(BiFunction!(T, Throwable, U) fn,
725 // //          Executor executor);
726 
727 // static if(is(T == void)) {
728 //     CompletionStage!(T) whenCompleteAsync(Action1!(Throwable) action);
729 //     CompletionStage!(T) whenComplete(Action1!(Throwable) action);
730 //     CompletionStage!(T) whenCompleteAsync(Action1!(Throwable) action, Executor executor);
731 // } else {
732 
733 //     /**
734 //      * Returns a new CompletionStage with the same result or exception as
735 //      * this stage, that executes the given action when this stage completes.
736 //      *
737 //      * <p>When this stage is complete, the given action is invoked
738 //      * with the result (or {@code null} if none) and the exception (or
739 //      * {@code null} if none) of this stage as arguments.  The returned
740 //      * stage is completed when the action returns.
741 //      *
742 //      * <p>Unlike method {@link #handle handle},
743 //      * this method is not designed to translate completion outcomes,
744 //      * so the supplied action should not throw an exception. However,
745 //      * if it does, the following rules apply: if this stage completed
746 //      * normally but the supplied action throws an exception, then the
747 //      * returned stage completes exceptionally with the supplied
748 //      * action's exception. Or, if this stage completed exceptionally
749 //      * and the supplied action throws an exception, then the returned
750 //      * stage completes exceptionally with this stage's exception.
751 //      *
752 //      * @param action the action to perform
753 //      * @return the new CompletionStage
754 //      */
755 //     CompletionStage!(T) whenComplete(BiConsumer!(T, Throwable) action);
756 
757 //     /**
758 //      * Returns a new CompletionStage with the same result or exception as
759 //      * this stage, that executes the given action using this stage's
760 //      * default asynchronous execution facility when this stage completes.
761 //      *
762 //      * <p>When this stage is complete, the given action is invoked with the
763 //      * result (or {@code null} if none) and the exception (or {@code null}
764 //      * if none) of this stage as arguments.  The returned stage is completed
765 //      * when the action returns.
766 //      *
767 //      * <p>Unlike method {@link #handleAsync(BiFunction) handleAsync},
768 //      * this method is not designed to translate completion outcomes,
769 //      * so the supplied action should not throw an exception. However,
770 //      * if it does, the following rules apply: If this stage completed
771 //      * normally but the supplied action throws an exception, then the
772 //      * returned stage completes exceptionally with the supplied
773 //      * action's exception. Or, if this stage completed exceptionally
774 //      * and the supplied action throws an exception, then the returned
775 //      * stage completes exceptionally with this stage's exception.
776 //      *
777 //      * @param action the action to perform
778 //      * @return the new CompletionStage
779 //      */
780 //     CompletionStage!(T) whenCompleteAsync(BiConsumer!(T, Throwable) action);
781 
782 //     /**
783 //      * Returns a new CompletionStage with the same result or exception as
784 //      * this stage, that executes the given action using the supplied
785 //      * Executor when this stage completes.
786 //      *
787 //      * <p>When this stage is complete, the given action is invoked with the
788 //      * result (or {@code null} if none) and the exception (or {@code null}
789 //      * if none) of this stage as arguments.  The returned stage is completed
790 //      * when the action returns.
791 //      *
792 //      * <p>Unlike method {@link #handleAsync(BiFunction,Executor) handleAsync},
793 //      * this method is not designed to translate completion outcomes,
794 //      * so the supplied action should not throw an exception. However,
795 //      * if it does, the following rules apply: If this stage completed
796 //      * normally but the supplied action throws an exception, then the
797 //      * returned stage completes exceptionally with the supplied
798 //      * action's exception. Or, if this stage completed exceptionally
799 //      * and the supplied action throws an exception, then the returned
800 //      * stage completes exceptionally with this stage's exception.
801 //      *
802 //      * @param action the action to perform
803 //      * @param executor the executor to use for asynchronous execution
804 //      * @return the new CompletionStage
805 //      */
806 //     CompletionStage!(T) whenCompleteAsync(BiConsumer!(T, Throwable) action, Executor executor);
807      
808 // }
809 //     /**
810 //      * Returns a new CompletionStage that, when this stage completes
811 //      * exceptionally, is executed with this stage's exception as the
812 //      * argument to the supplied function.  Otherwise, if this stage
813 //      * completes normally, then the returned stage also completes
814 //      * normally with the same value.
815 //      *
816 //      * @param fn the function to use to compute the value of the
817 //      * returned CompletionStage if this CompletionStage completed
818 //      * exceptionally
819 //      * @return the new CompletionStage
820 //      */
821 //     CompletionStage!(T) exceptionally(Function!(Throwable, T) fn);
822 
823 //     /**
824 //      * Returns a {@link CompletableFuture} maintaining the same
825 //      * completion properties as this stage. If this stage is already a
826 //      * CompletableFuture, this method may return this stage itself.
827 //      * Otherwise, invocation of this method may be equivalent in
828 //      * effect to {@code thenApply(x -> x)}, but returning an instance
829 //      * of type {@code CompletableFuture}.
830 //      *
831 //      * @return the CompletableFuture
832 //      */
833 //     CompletionStage!(T) toCompletableFuture();
834     
835 
836 // }