Package org.jenkinsci.plugins.workflow.support.concurrent

Class Futures

  • @Deprecated
public abstract class Futures
extends Object
    Deprecated.
    Various convenience methods for working with ListenableFutures.

    Mostly copied after Guava's Futures, because that one is still marked as beta and is subject to change.

    Author:
    Guava

    • Constructor Summary

      Constructors 
      Constructor Description
      Futures()
      Deprecated.
       

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static <V> void addCallback​(com.google.common.util.concurrent.ListenableFuture<V> future, com.google.common.util.concurrent.FutureCallback<? super V> callback)
      Deprecated.
      Registers separate success and failure callbacks to be run when the Future's computation is complete or, if the computation is already complete, immediately.
      static <V> void addCallback​(com.google.common.util.concurrent.ListenableFuture<V> future, com.google.common.util.concurrent.FutureCallback<? super V> callback, Executor executor)
      Deprecated.
      Registers separate success and failure callbacks to be run when the Future's computation is complete or, if the computation is already complete, immediately.
      static <V> com.google.common.util.concurrent.ListenableFuture<List<V>> allAsList​(com.google.common.util.concurrent.ListenableFuture<? extends V>... futures)
      Deprecated.
      Creates a new ListenableFuture whose value is a list containing the values of all its input futures, if all succeed.
      static <V> com.google.common.util.concurrent.ListenableFuture<List<V>> allAsList​(Iterable<? extends com.google.common.util.concurrent.ListenableFuture<? extends V>> futures)
      Deprecated.
      Creates a new ListenableFuture whose value is a list containing the values of all its input futures, if all succeed.
      static <V> com.google.common.util.concurrent.ListenableFuture<V> immediateFailedFuture​(Throwable throwable)
      Deprecated.
      Returns a ListenableFuture which has an exception set immediately upon construction.
      static <V> com.google.common.util.concurrent.ListenableFuture<V> immediateFuture​(V value)
      Deprecated.
      Creates a ListenableFuture which has its value set immediately upon construction.
      static <I,​O>
      com.google.common.util.concurrent.ListenableFuture<O>      		 transform​(com.google.common.util.concurrent.ListenableFuture<I> input, com.google.common.base.Function<? super I,​? extends O> function)
      Deprecated.
      Returns a new ListenableFuture whose result is the product of applying the given Function to the result of the given Future.
      static <I,​O>
      com.google.common.util.concurrent.ListenableFuture<O>      		 transform​(com.google.common.util.concurrent.ListenableFuture<I> input, com.google.common.base.Function<? super I,​? extends O> function, Executor executor)
      Deprecated.
      Returns a new ListenableFuture whose result is the product of applying the given Function to the result of the given Future.
      static <I,​O>
      com.google.common.util.concurrent.ListenableFuture<O>      		 transform​(com.google.common.util.concurrent.ListenableFuture<I> input, com.google.common.util.concurrent.AsyncFunction<? super I,​? extends O> function)
      Deprecated.
      Returns a new ListenableFuture whose result is asynchronously derived from the result of the given Future.
      static <I,​O>
      com.google.common.util.concurrent.ListenableFuture<O>      		 transform​(com.google.common.util.concurrent.ListenableFuture<I> input, com.google.common.util.concurrent.AsyncFunction<? super I,​? extends O> function, Executor executor)
      Deprecated.
      Returns a new ListenableFuture whose result is asynchronously derived from the result of the given Future.

    • Constructor Detail

      • Futures

        public Futures()
        Deprecated.

    • Method Detail

      • addCallback

        public static <V> void addCallback​(com.google.common.util.concurrent.ListenableFuture<V> future,
                                   com.google.common.util.concurrent.FutureCallback<? super V> callback)
        Deprecated.
        Registers separate success and failure callbacks to be run when the Future's computation is complete or, if the computation is already complete, immediately.

        There is no guaranteed ordering of execution of callbacks, but any callback added through this method is guaranteed to be called once the computation is complete. Example: 

         
 ListenableFuture<QueryResult> future = ...;
 addCallback(future,
     new FutureCallback<QueryResult> {
       public void onSuccess(QueryResult result) {
         storeInCache(result);
       }
       public void onFailure(Throwable t) {
         reportError(t);
       }
     });
        Note: If the callback is slow or heavyweight, consider supplying an executor. If you do not supply an executor, addCallback will use a direct executor, which carries some caveats for heavier operations. For example, the callback may run on an unpredictable or undesirable thread:
        • If the input Future is done at the time addCallback is called, addCallback will execute the callback inline.
        • If the input Future is not yet done, addCallback will schedule the callback to be run by the thread that completes the input Future, which may be an internal system thread such as an RPC network thread.
        Also note that, regardless of which thread executes the callback, all other registered but unexecuted listeners are prevented from running during its execution, even if those listeners are to run in other executors.

        For a more general interface to attach a completion listener to a Future, see addListener.

        Parameters:
        future - The future attach the callback to.
        callback - The callback to invoke when future is completed.
        Since:
        10.0

      • addCallback

        public static <V> void addCallback​(com.google.common.util.concurrent.ListenableFuture<V> future,
                                   com.google.common.util.concurrent.FutureCallback<? super V> callback,
                                   Executor executor)
        Deprecated.
        Registers separate success and failure callbacks to be run when the Future's computation is complete or, if the computation is already complete, immediately.

        The callback is run in executor. There is no guaranteed ordering of execution of callbacks, but any callback added through this method is guaranteed to be called once the computation is complete. Example: 

         
 ListenableFuture<QueryResult> future = ...;
 Executor e = ...
 addCallback(future, e,
     new FutureCallback<QueryResult> {
       public void onSuccess(QueryResult result) {
         storeInCache(result);
       }
       public void onFailure(Throwable t) {
         reportError(t);
       }
     });
        When the callback is fast and lightweight, consider omitting the executor or explicitly specifying directExecutor. However, be aware of the caveats documented in the link above.

        For a more general interface to attach a completion listener to a Future, see addListener.

        Parameters:
        future - The future attach the callback to.
        callback - The callback to invoke when future is completed.
        executor - The executor to run callback when the future completes.
        Since:
        10.0

      • immediateFuture

        public static <V> com.google.common.util.concurrent.ListenableFuture<V> immediateFuture​(@Nullable
                                                                                        V value)
        Deprecated.
        Creates a ListenableFuture which has its value set immediately upon construction. The getters just return the value. This Future can't be canceled or timed out and its isDone() method always returns true.

      • immediateFailedFuture

        public static <V> com.google.common.util.concurrent.ListenableFuture<V> immediateFailedFuture​(Throwable throwable)
        Deprecated.
        Returns a ListenableFuture which has an exception set immediately upon construction.

        The returned Future can't be cancelled, and its isDone() method always returns true. Calling get() will immediately throw the provided Throwable wrapped in an ExecutionException.

        Throws:
        Error - if the throwable is an Error.

      • transform

        public static <I,​O> com.google.common.util.concurrent.ListenableFuture<O> transform​(com.google.common.util.concurrent.ListenableFuture<I> input,
                                                                                          com.google.common.util.concurrent.AsyncFunction<? super I,​? extends O> function)
        Deprecated.
        Returns a new ListenableFuture whose result is asynchronously derived from the result of the given Future. More precisely, the returned Future takes its result from a Future produced by applying the given AsyncFunction to the result of the original Future. Example: 
           
   ListenableFuture<RowKey> rowKeyFuture = indexService.lookUp(query);
   AsyncFunction<RowKey, QueryResult> queryFunction =
       new AsyncFunction<RowKey, QueryResult>() {
         public ListenableFuture<QueryResult> apply(RowKey rowKey) {
           return dataService.read(rowKey);
         }
       };
   ListenableFuture<QueryResult> queryFuture =
       transform(rowKeyFuture, queryFunction);
        Note: If the derived Future is slow or heavyweight to create (whether the Future itself is slow or heavyweight to complete is irrelevant), consider supplying an executor. If you do not supply an executor, transform will use a direct executor, which carries some caveats for heavier operations. For example, the call to function.apply may run on an unpredictable or undesirable thread:
        • If the input Future is done at the time transform is called, transform will call function.apply inline.
        • If the input Future is not yet done, transform will schedule function.apply to be run by the thread that completes the input Future, which may be an internal system thread such as an RPC network thread.
        Also note that, regardless of which thread executes function.apply, all other registered but unexecuted listeners are prevented from running during its execution, even if those listeners are to run in other executors.

        The returned Future attempts to keep its cancellation state in sync with that of the input future and that of the future returned by the function. That is, if the returned Future is cancelled, it will attempt to cancel the other two, and if either of the other two is cancelled, the returned Future will receive a callback in which it will attempt to cancel itself.

        Parameters:
        input - The future to transform
        function - A function to transform the result of the input future to the result of the output future
        Returns:
        A future that holds result of the function (if the input succeeded) or the original input's failure (if not)
        Since:
        11.0

      • transform

        public static <I,​O> com.google.common.util.concurrent.ListenableFuture<O> transform​(com.google.common.util.concurrent.ListenableFuture<I> input,
                                                                                          com.google.common.util.concurrent.AsyncFunction<? super I,​? extends O> function,
                                                                                          Executor executor)
        Deprecated.
        Returns a new ListenableFuture whose result is asynchronously derived from the result of the given Future. More precisely, the returned Future takes its result from a Future produced by applying the given AsyncFunction to the result of the original Future. Example: 
           
   ListenableFuture<RowKey> rowKeyFuture = indexService.lookUp(query);
   AsyncFunction<RowKey, QueryResult> queryFunction =
       new AsyncFunction<RowKey, QueryResult>() {
         public ListenableFuture<QueryResult> apply(RowKey rowKey) {
           return dataService.read(rowKey);
         }
       };
   ListenableFuture<QueryResult> queryFuture =
       transform(rowKeyFuture, queryFunction, executor);

        The returned Future attempts to keep its cancellation state in sync with that of the input future and that of the future returned by the chain function. That is, if the returned Future is cancelled, it will attempt to cancel the other two, and if either of the other two is cancelled, the returned Future will receive a callback in which it will attempt to cancel itself.

        When the execution of function.apply is fast and lightweight (though the Future it returns need not meet these criteria), consider omitting the executor or explicitly specifying directExecutor. However, be aware of the caveats documented in the link above.

        Parameters:
        input - The future to transform
        function - A function to transform the result of the input future to the result of the output future
        executor - Executor to run the function in.
        Returns:
        A future that holds result of the function (if the input succeeded) or the original input's failure (if not)
        Since:
        11.0

      • transform

        public static <I,​O> com.google.common.util.concurrent.ListenableFuture<O> transform​(com.google.common.util.concurrent.ListenableFuture<I> input,
                                                                                          com.google.common.base.Function<? super I,​? extends O> function)
        Deprecated.
        Returns a new ListenableFuture whose result is the product of applying the given Function to the result of the given Future. Example: 
           
   ListenableFuture<QueryResult> queryFuture = ...;
   Function<QueryResult, List<Row>> rowsFunction =
       new Function<QueryResult, List<Row>>() {
         public List<Row> apply(QueryResult queryResult) {
           return queryResult.getRows();
         }
       };
   ListenableFuture<List<Row>> rowsFuture =
       transform(queryFuture, rowsFunction);
        Note: If the transformation is slow or heavyweight, consider supplying an executor. If you do not supply an executor, transform will use an inline executor, which carries some caveats for heavier operations. For example, the call to function.apply may run on an unpredictable or undesirable thread:
        • If the input Future is done at the time transform is called, transform will call function.apply inline.
        • If the input Future is not yet done, transform will schedule function.apply to be run by the thread that completes the input Future, which may be an internal system thread such as an RPC network thread.
        Also note that, regardless of which thread executes function.apply, all other registered but unexecuted listeners are prevented from running during its execution, even if those listeners are to run in other executors.

        The returned Future attempts to keep its cancellation state in sync with that of the input future. That is, if the returned Future is cancelled, it will attempt to cancel the input, and if the input is cancelled, the returned Future will receive a callback in which it will attempt to cancel itself.

        An example use of this method is to convert a serializable object returned from an RPC into a POJO.

        Parameters:
        input - The future to transform
        function - A Function to transform the results of the provided future to the results of the returned future. This will be run in the thread that notifies input it is complete.
        Returns:
        A future that holds result of the transformation.
        Since:
        9.0 (in 1.0 as compose)

      • transform

        public static <I,​O> com.google.common.util.concurrent.ListenableFuture<O> transform​(com.google.common.util.concurrent.ListenableFuture<I> input,
                                                                                          com.google.common.base.Function<? super I,​? extends O> function,
                                                                                          Executor executor)
        Deprecated.
        Returns a new ListenableFuture whose result is the product of applying the given Function to the result of the given Future. Example: 
           
   ListenableFuture<QueryResult> queryFuture = ...;
   Function<QueryResult, List<Row>> rowsFunction =
       new Function<QueryResult, List<Row>>() {
         public List<Row> apply(QueryResult queryResult) {
           return queryResult.getRows();
         }
       };
   ListenableFuture<List<Row>> rowsFuture =
       transform(queryFuture, rowsFunction, executor);

        The returned Future attempts to keep its cancellation state in sync with that of the input future. That is, if the returned Future is cancelled, it will attempt to cancel the input, and if the input is cancelled, the returned Future will receive a callback in which it will attempt to cancel itself.

        An example use of this method is to convert a serializable object returned from an RPC into a POJO.

        When the transformation is fast and lightweight, consider omitting the executor or explicitly specifying directExecutor. However, be aware of the caveats documented in the link above.

        Parameters:
        input - The future to transform
        function - A Function to transform the results of the provided future to the results of the returned future.
        executor - Executor to run the function in.
        Returns:
        A future that holds result of the transformation.
        Since:
        9.0 (in 2.0 as compose)

      • allAsList

        @Beta
public static <V> com.google.common.util.concurrent.ListenableFuture<List<V>> allAsList​(com.google.common.util.concurrent.ListenableFuture<? extends V>... futures)
        Deprecated.
        Creates a new ListenableFuture whose value is a list containing the values of all its input futures, if all succeed. If any input fails, the returned future fails.

        The list of results is in the same order as the input list.

        Canceling this future does not cancel any of the component futures; however, if any of the provided futures fails or is canceled, this one is, too.

        Parameters:
        futures - futures to combine
        Returns:
        a future that provides a list of the results of the component futures
        Since:
        10.0

      • allAsList

        @Beta
public static <V> com.google.common.util.concurrent.ListenableFuture<List<V>> allAsList​(Iterable<? extends com.google.common.util.concurrent.ListenableFuture<? extends V>> futures)
        Deprecated.
        Creates a new ListenableFuture whose value is a list containing the values of all its input futures, if all succeed. If any input fails, the returned future fails.

        The list of results is in the same order as the input list.

        Canceling this future does not cancel any of the component futures; however, if any of the provided futures fails or is canceled, this one is, too.

        Parameters:
        futures - futures to combine
        Returns:
        a future that provides a list of the results of the component futures
        Since:
        10.0