1 /*
2 * Copyright 2013 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 * http://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.netty.util.concurrent;
17
18 import java.util.concurrent.CancellationException;
19 import java.util.concurrent.TimeUnit;
20
21
22 /**
23 * The result of an asynchronous operation.
24 */
25 @SuppressWarnings("ClassNameSameAsAncestorName")
26 public interface Future<V> extends java.util.concurrent.Future<V> {
27
28 /**
29 * Returns {@code true} if and only if the I/O operation was completed
30 * successfully.
31 */
32 boolean isSuccess();
33
34 /**
35 * returns {@code true} if and only if the operation can be cancelled via {@link #cancel(boolean)}.
36 */
37 boolean isCancellable();
38
39 /**
40 * Returns the cause of the failed I/O operation if the I/O operation has
41 * failed.
42 *
43 * @return the cause of the failure.
44 * {@code null} if succeeded or this future is not
45 * completed yet.
46 */
47 Throwable cause();
48
49 /**
50 * Adds the specified listener to this future. The
51 * specified listener is notified when this future is
52 * {@linkplain #isDone() done}. If this future is already
53 * completed, the specified listener is notified immediately.
54 */
55 Future<V> addListener(GenericFutureListener<? extends Future<? super V>> listener);
56
57 /**
58 * Adds the specified listeners to this future. The
59 * specified listeners are notified when this future is
60 * {@linkplain #isDone() done}. If this future is already
61 * completed, the specified listeners are notified immediately.
62 */
63 Future<V> addListeners(GenericFutureListener<? extends Future<? super V>>... listeners);
64
65 /**
66 * Removes the first occurrence of the specified listener from this future.
67 * The specified listener is no longer notified when this
68 * future is {@linkplain #isDone() done}. If the specified
69 * listener is not associated with this future, this method
70 * does nothing and returns silently.
71 */
72 Future<V> removeListener(GenericFutureListener<? extends Future<? super V>> listener);
73
74 /**
75 * Removes the first occurrence for each of the listeners from this future.
76 * The specified listeners are no longer notified when this
77 * future is {@linkplain #isDone() done}. If the specified
78 * listeners are not associated with this future, this method
79 * does nothing and returns silently.
80 */
81 Future<V> removeListeners(GenericFutureListener<? extends Future<? super V>>... listeners);
82
83 /**
84 * Waits for this future until it is done, and rethrows the cause of the failure if this future
85 * failed.
86 */
87 Future<V> sync() throws InterruptedException;
88
89 /**
90 * Waits for this future until it is done, and rethrows the cause of the failure if this future
91 * failed.
92 */
93 Future<V> syncUninterruptibly();
94
95 /**
96 * Waits for this future to be completed.
97 *
98 * @throws InterruptedException
99 * if the current thread was interrupted
100 */
101 Future<V> await() throws InterruptedException;
102
103 /**
104 * Waits for this future to be completed without
105 * interruption. This method catches an {@link InterruptedException} and
106 * discards it silently.
107 */
108 Future<V> awaitUninterruptibly();
109
110 /**
111 * Waits for this future to be completed within the
112 * specified time limit.
113 *
114 * @return {@code true} if and only if the future was completed within
115 * the specified time limit
116 *
117 * @throws InterruptedException
118 * if the current thread was interrupted
119 */
120 boolean await(long timeout, TimeUnit unit) throws InterruptedException;
121
122 /**
123 * Waits for this future to be completed within the
124 * specified time limit.
125 *
126 * @return {@code true} if and only if the future was completed within
127 * the specified time limit
128 *
129 * @throws InterruptedException
130 * if the current thread was interrupted
131 */
132 boolean await(long timeoutMillis) throws InterruptedException;
133
134 /**
135 * Waits for this future to be completed within the
136 * specified time limit without interruption. This method catches an
137 * {@link InterruptedException} and discards it silently.
138 *
139 * @return {@code true} if and only if the future was completed within
140 * the specified time limit
141 */
142 boolean awaitUninterruptibly(long timeout, TimeUnit unit);
143
144 /**
145 * Waits for this future to be completed within the
146 * specified time limit without interruption. This method catches an
147 * {@link InterruptedException} and discards it silently.
148 *
149 * @return {@code true} if and only if the future was completed within
150 * the specified time limit
151 */
152 boolean awaitUninterruptibly(long timeoutMillis);
153
154 /**
155 * Return the result without blocking. If the future is not done yet this will return {@code null}.
156 *
157 * As it is possible that a {@code null} value is used to mark the future as successful you also need to check
158 * if the future is really done with {@link #isDone()} and not relay on the returned {@code null} value.
159 */
160 V getNow();
161
162 /**
163 * {@inheritDoc}
164 *
165 * If the cancellation was successful it will fail the future with an {@link CancellationException}.
166 */
167 @Override
168 boolean cancel(boolean mayInterruptIfRunning);
169 }