geario.concurrency.Future source code

1 /*
2  * Hunt - A cross-platform abstraction library with asynchronous I/O.
3  *
4  * Copyright (C) 2021-2022 Kerisy.com
5  *
6  * Website: https://www.kerisy.com
7  *
8  * Licensed under the Apache-2.0 License.
9  *
10  */
11 
12 module geario.concurrency.Future;
13 
14 import core.time;
15 
16 /**
17  * A {@code Future} represents the result of an asynchronous
18  * computation.  Methods are provided to check if the computation is
19  * complete, to wait for its completion, and to retrieve the result of
20  * the computation.  The result can only be retrieved using method
21  * {@code get} when the computation has completed, blocking if
22  * necessary until it is ready.  Cancellation is performed by the
23  * {@code cancel} method.  Additional methods are provided to
24  * determine if the task completed normally or was cancelled. Once a
25  * computation has completed, the computation cannot be cancelled.
26  * If you would like to use a {@code Future} for the sake
27  * of cancellability but not provide a usable result, you can
28  * declare types of the form {@code Future!T} and
29  * return {@code null} as a result of the underlying task.
30  *
31  */
32 interface Future(V) {
33 
34     /**
35      * Waits if necessary for the computation to complete, and then
36      * retrieves its result.
37      *
38      * @return the computed result
39      * @throws CancellationException if the computation was cancelled
40      * @throws ExecutionException if the computation threw an
41      * exception
42      * @throws InterruptedException if the current thread was interrupted
43      * while waiting
44      */
45     V Get();
46 
47     /**
48      * Waits if necessary for at most the given time for the computation
49      * to complete, and then retrieves its result, if available.
50      *
51      * @param timeout the maximum time to wait
52      * @param unit the time unit of the timeout argument
53      * @return the computed result
54      * @throws CancellationException if the computation was cancelled
55      * @throws ExecutionException if the computation threw an
56      * exception
57      * @throws InterruptedException if the current thread was interrupted
58      * while waiting
59      * @throws TimeoutException if the wait timed out
60      */
61     V Get(Duration timeout);
62 
63 
64     /**
65      * Attempts to cancel execution of this task.  This attempt will
66      * fail if the task has already completed, has already been cancelled,
67      * or could not be cancelled for some other reason. If successful,
68      * and this task has not started when {@code cancel} is called,
69      * this task should never run.  If the task has already started,
70      * then the {@code mayInterruptIfRunning} parameter determines
71      * whether the thread executing this task should be interrupted in
72      * an attempt to stop the task.
73      */
74     bool Cancel(bool mayInterruptIfRunning);
75 
76     /**
77      * Returns {@code true} if this task was cancelled before it completed
78      * normally.
79      *
80      * @return {@code true} if this task was cancelled before it completed
81      */
82     bool IsCancelled();
83 
84     /**
85      * Returns {@code true} if this task completed.
86      *
87      * Completion may be due to normal termination, an exception, or
88      * cancellation -- in all of these cases, this method will return
89      * {@code true}.
90      *
91      * @return {@code true} if this task completed
92      */
93     bool IsDone();    
94 }
95