1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
/*******************************************************************************
* Copyright (c) 2010, 2013 EclipseSource and others. All rights reserved. This
* program and the accompanying materials are made available under the terms of
* the Eclipse Public License v1.0 which accompanies this distribution, and is
* available at http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* EclipseSource - initial API and implementation
* Gunnar Wagenknecht - added support for generics
******************************************************************************/
package org.eclipse.equinox.concurrent.future;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.OperationCanceledException;
/**
* <p>
* A future represents the future outcome of some operation(s).
* </p>
* <p>
* The expected usage of a future is as a return value from some operation that
* is to be executed asynchronously and then return some result.
* </p>
* <p>
* So, for example, a simple usage of an IFuture would be:
*
* <pre>
* IFuture future = foo();
* ...
* Object result = future.get();
* </pre>
*
* Clients generally will hold onto the future for some amount of time, and then
* call {@link #get()} or {@link #get(long)} to retrieve the result of the
* operation. They may also call {@link #hasValue()} to determine whether any
* values have been provided to the future (if <code>true</code>, meaning that
* subsequent calls to {@link #get()} will not block), or {@link #isDone()} to
* determine if <b>all</b> operations and results have been completed.
* </p>
* <p>
* If {@link #hasValue()} is true, then the client may access status information
* associated with the completed operation(s) via {@link #getStatus()}. Until
* {@link #hasValue()} is <code>true</code>, {@link #getStatus()} will be
* <code>null</code>.
* </p>
*
* @see IStatus
* @param <ResultType>
* the type that will be returned by {@link #get()} and/or
* {@link #get(long)}
* @since 1.1
*
*/
public interface IFuture<ResultType> {
/**
* Cancel the operation
*
* @return <tt>false</tt> if the operation could not be canceled, typically
* because it has already completed normally; <tt>true</tt>
* otherwise
*/
public boolean cancel();
/**
* Waits if necessary for one or more operations to complete, and then
* returns result(s). This method will block until either a) at least one
* result is available; or b) at least one operation throws an exception.
*
* @return Object result of the asynchronous operation(s)
* @throws InterruptedException
* if thread calling this method is interrupted.
* @throws OperationCanceledException
* if the operation has been canceled via progress monitor
* {@link #getProgressMonitor()}.
*/
ResultType get() throws InterruptedException, OperationCanceledException;
/**
* Waits if necessary for one or more operations to complete, and then
* returns result(s). This method will block until either a) at least one
* result is available; or b) at least one operation throws an exception.
*
* @param waitTimeInMillis
* the maximum time to wait in milliseconds for the operation(s)
* to complete.
* @return Object result of the asynchronous operation(s)
* @throws InterruptedException
* if thread calling this method is interrupted.
* @throws TimeoutException
* if the given wait time is exceeded without getting result.
* @throws OperationCanceledException
* if the operation has been canceled via progress monitor
* {@link #getProgressMonitor()}.
*/
ResultType get(long waitTimeInMillis) throws InterruptedException,
TimeoutException, OperationCanceledException;
/**
* <p>
* Get status for operation. Will return <code>null</code> until at least
* one operation(s) are complete.
* </p>
* <p>
* If {@link #hasValue()} returns <code>true</code>, this method will return
* a non-<code>null</code> IStatus. If {@link #hasValue()} returns
* <code>false</code>, this method will return <code>null</code>.
* </p>
* <p>
* Note that the returned IStatus instance may be an IMultiStatus, meaning
* that multiple operations have completed or are pending completion.
* </p>
*
* @return IStatus the status of completed operation(s). Will return
* <code>null</code> if {@link #hasValue()} returns
* <code>false</code>.
*
* @see #hasValue()
*/
public IStatus getStatus();
/**
* <p>
* Returns <tt>true</tt> if <b>any</b> underlying operation(s) have
* completed.
* </p>
* <p>
* If this future represents access to just one operation, then this method
* and {@link #isDone()} will always return the same value. That is, when a
* single operation has a value, it is then considered done/completed and
* both {@link #isDone()} and this method will return <code>true</code>.
* </p>
* <p>
* If this future represents multiple operations, then this method will
* return <code>true</code> when <b>any</b> of the operations have
* completed. Until the first operation is completed, it will return
* <code>false</code>.
* </p>
*
* @return <tt>true</tt> if any operations represented by this future have
* completed.
*/
boolean hasValue();
/**
* <p>
* Returns <tt>true</tt> if <b>all</b> underlying operation(s) have been
* completed.
* </p>
* <p>
* If this future represents access to just one operation, then this method
* and {@link #hasValue()} will always return the same value. That is, when
* a single operation has a value, it is then considered done/completed and
* both {@link #hasValue()} and #isDone will return <code>true</code>.
* </p>
* <p>
* If this future represents multiple operations, then this method will only
* return <code>true</code> when <b>all</b> of the operations have
* completed. Until all operations have completed, it will return
* <code>false</code>.
* </p>
* <p>
* Completion can be due to normal operation completion, an exception, or
* user cancellation -- in all of these cases, this method will return
* <tt>true</tt> if all underlying operation(s) have been completed.
* </p>
*
* @return <tt>true</tt> if all operation(s) have completed in some manner.
*/
boolean isDone();
}
|
