| /******************************************************************************* |
| * 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(); |
| |
| } |