| /****************************************************************************** |
| . |
| . This |
| * program and the accompanying materials are made available under the terms of |
| * the Eclipse Public License 2.0 which accompanies this distribution, and is |
| t https://www.eclipse.org/legal/epl-2.0/ |
| t |
| t SPDX-License-Identifier: EPL-2.0 |
| * |
| * Contributors: |
| * EclipseSource - initial API and implementation |
| * Gunnar Wagenknecht - added support for generics |
| ******************************************************************************/ |
| package org.eclipse.equinox.concurrent.future; |
| |
| import org.eclipse.core.runtime.IProgressMonitor; |
| |
| /** |
| * <p> |
| * Contract for the actual execution of {@link IProgressRunnable}s. Instances of |
| * this interface must be able to provide resources to eventually execute a |
| * given {@link IProgressRunnable}, upon calling |
| * {@link #execute(IProgressRunnable, IProgressMonitor)}. |
| * </p> |
| * <p> |
| * Note that implementations may decide what/how to execute the given |
| * IProgressRunnable (i.e. via a {@link Thread}, or a Job, or a ThreadPool or |
| * some other invocation mechanism. But the intended contract of |
| * {@link #execute(IProgressRunnable, IProgressMonitor)} is that the |
| * {@link IProgressRunnable#run(IProgressMonitor)} method will be invoked by |
| * this executor in a timely manner <b>without</b> blocking. |
| * </p> |
| * |
| * @see IProgressRunnable |
| * @see IFuture |
| * @see #execute(IProgressRunnable, IProgressMonitor) |
| * @since 1.1 |
| */ |
| public interface IExecutor { |
| |
| /** |
| * <p> |
| * Execute the given {@link IProgressRunnable} (i.e. call |
| * {@link IProgressRunnable#run(IProgressMonitor)}. Will return a non- |
| * <code>null</code> instance of {@link IFuture} that allows clients to |
| * inspect the state of the execution and retrieve any results via |
| * {@link IFuture#get()} or {@link IFuture#get(long)}. |
| * </p> |
| * <p> |
| * Note that implementers may decide whether to invoke |
| * {@link IProgressRunnable#run(IProgressMonitor)} asynchronously or |
| * synchronously, but since IProgressRunnables are frequently going to be |
| * longer-running operations, implementers should proceed carefully before |
| * implementing with synchronous (blocking) invocation. Implementers should |
| * typically implement via some non-blocking asynchronous invocation |
| * mechanism, e.g. Threads, Jobs, ThreadPools etc. |
| * </p> |
| * |
| * @param runnable |
| * the {@link IProgressRunnable} to invoke. Must not be |
| * <code>null</code>. |
| * @param monitor |
| * any {@link IProgressMonitor} to be passed to the runnable. May |
| * be <code>null</code>. |
| * @return {@link IFuture} to allow for inspection of the state of the |
| * computation by clients, as well as access to any return values of |
| * {@link IProgressRunnable#run(IProgressMonitor)}. Will not be |
| * <code>null</code>. |
| * @param <ResultType> |
| * the type that will be returned by the |
| * {@link IProgressRunnable} as well as the returned |
| * {@link IFuture} |
| */ |
| <ResultType> IFuture<ResultType> execute( |
| IProgressRunnable<? extends ResultType> runnable, |
| IProgressMonitor monitor); |
| |
| } |