1 /*
2 * Copyright 2021 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty5.util.concurrent;
17
18 import java.util.concurrent.CancellationException;
19
20 /**
21 * A result of an asynchronous operation.
22 * <p>
23 * This interface is used as the super-interface of {@link Promise} and {@link Future}, and these should generally be
24 * used instead.
25 */
26 interface AsynchronousResult<V> {
27 /**
28 * Cancel this asynchronous operation, unless it has already been completed
29 * or is not {@linkplain #isCancellable() cancellable}.
30 * <p>
31 * A cancelled operation is considered to be {@linkplain #isDone() done} and {@linkplain #isFailed() failed}.
32 * <p>
33 * If the cancellation was successful, the result of this operation will be that it has failed with a
34 * {@link CancellationException}.
35 * <p>
36 * Cancellation will not cause any threads working on the operation to be {@linkplain Thread#interrupt()
37 * interrupted}.
38 *
39 * @return {@code true} if the operation was cancelled by this call, otherwise {@code false}.
40 */
41 boolean cancel();
42
43 /**
44 * Returns {@code true} if and only if the operation was completed successfully.
45 */
46 boolean isSuccess();
47
48 /**
49 * Returns {@code true} if and only if the operation was completed and failed.
50 */
51 boolean isFailed();
52
53 /**
54 * Return {@code true} if this operation has been {@linkplain #cancel() cancelled}.
55 *
56 * @return {@code true} if this operation has been cancelled, otherwise {@code false}.
57 */
58 boolean isCancelled();
59
60 /**
61 * Return {@code true} if this operation has been completed either {@linkplain Promise#setSuccess(Object)
62 * successfully}, {@linkplain Promise#setFailure(Throwable) unsuccessfully}, or through
63 * {@linkplain #cancel() cancellation}.
64 *
65 * @return {@code true} if this operation has completed, otherwise {@code false}.
66 */
67 boolean isDone();
68
69 /**
70 * Returns {@code true} if and only if the operation can be cancelled via {@link #cancel()}.
71 * Note that this is inherently racy, as the operation could be made
72 * {@linkplain Promise#setUncancellable() uncancellable} at any time.
73 *
74 * @return {@code true} if this operation can be cancelled.
75 */
76 boolean isCancellable();
77
78 /**
79 * Return the successful result of this asynchronous operation, if any.
80 * If the operation has not yet been completed, then this will throw {@link IllegalStateException}.
81 * If the operation has been cancelled or failed with an exception, then this returns {@code null}.
82 * Note that asynchronous operations can also be completed successfully with a {@code null} result.
83 *
84 * @return the result of this operation, if completed successfully.
85 * @throws IllegalStateException if this {@code Future} or {@link Promise} has not completed yet.
86 */
87 V getNow();
88
89 /**
90 * Returns the cause of the failed operation if the operation has failed.
91 *
92 * @return The cause of the failure, if any. Otherwise {@code null} if succeeded.
93 * @throws IllegalStateException if this {@code Promise} has not completed yet.
94 */
95 Throwable cause();
96
97 /**
98 * Returns the {@link EventExecutor} that is tied to this {@link Promise} or {@link Future}.
99 */
100 EventExecutor executor();
101 }