Package jadex.commons.future

Class Future<E>

    • Constructor Summary

      Constructors 
      Constructor Description
      Future()
      Create a new future.
      Future​(E result)
      Create a future that is already done.
      Future​(java.lang.Exception exception)
      Create a future that is already failed.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void abortGet​(ISuspendable caller)
      Abort a blocking get call.
      void addResultListener​(IResultListener<E> listener)
      Add a result listener.
      <T> IFuture<E> catchEx​(Future<T> delegate)
      Called on exception.
      IFuture<E> catchEx​(java.util.function.Consumer<? super java.lang.Exception> consumer)
      Called on exception.
      IFuture<E> catchEx​(java.util.function.Consumer<? super java.lang.Exception> consumer, java.lang.Class<?> futuretype)
      Called on exception.
      void delegate​(Future<E> delegate)
      Deprecated.
      Use delegateTo.
      void delegateFrom​(IFuture<E> source)
      Delegate the result and exception from another future.
      void delegateTo​(Future<E> target)
      Forward the result and exception to another future.
      protected boolean doAddResultListener​(IResultListener<E> listener)
      Add a listener and check if it should be notified immediately due to the future already being finished before add.
      protected boolean doSetException​(java.lang.Exception exception, boolean undone)
      Set the exception (internal implementation for normal and if-undone).
      protected boolean doSetResult​(E result, boolean undone)
      Set the result without notifying listeners.
      protected static <T> void doStartScheduledNotifications()
      Start scheduled listener notifications.
      protected void executeNotification​(IResultListener<E> listener, ICommand<IResultListener<E>> command)
      Execute a notification.
      E get()
      Get the result - blocking call.
      E get​(boolean realtime)
      Get the result - blocking call.
      E get​(long timeout)
      Get the result - blocking call.
      E get​(long timeout, boolean realtime)
      Get the result - blocking call.
      E get​(ThreadSuspendable sus)
      Deprecated.
      - From 3.0.
      static <T> IFuture<T> getEmptyFuture()
      Get the empty future of some type.
      java.lang.Exception getException()
      Get the exception, if any.
      <T> Future<T> getFuture​(java.lang.Class<?> futuretype)
      Sequential execution of async methods via implicit delegation.
      protected ICommand<IResultListener<E>> getNotificationCommand()
      Get the notification command.
      boolean hasResultListener()
      Check, if the future has at least one listener.
      boolean isDone()
      Test if done, i.e.
      boolean isNotified()
      Was the result/exception (scheduled to be) notified to some listener/blocked caller?
      protected void resume()
      Resume after result or exception has been set.
      protected void scheduleNotification​(IResultListener<E> listener, ICommand<IResultListener<E>> command)
      Schedule a listener notification for a specific listener to be executed outside the synchronized block.
      protected boolean scheduleNotification​(IFilter<IResultListener<E>> filter, ICommand<IResultListener<E>> command)
      Schedule a notification for selected listeners.
      void sendForwardCommand​(java.lang.Object command)
      Send a (forward) command to the listeners.
      void setException​(java.lang.Exception exception)
      Set the exception.
      boolean setExceptionIfUndone​(java.lang.Exception exception)
      Set the exception.
      void setResult​(E result)
      Set the result.
      boolean setResultIfUndone​(E result)
      Set the result.
      protected static void startScheduledNotifications()
      Start scheduled listener notifications using stack compaction, if desired.
      IFuture<? extends E> then​(java.util.function.Consumer<? super E> function)
      Applies a function after the result is available, using the result of this Future as input.
      IFuture<java.lang.Void> thenAccept​(java.util.function.Consumer<? super E> consumer)  
      IFuture<java.lang.Void> thenAccept​(java.util.function.Consumer<? super E> consumer, java.lang.Class<?> futuretype)  
      <T> IFuture<T> thenApply​(java.util.function.Function<? super E,​? extends T> function)
      Applies a function after the result is available, using the result of this Future as input.
      <T> IFuture<T> thenApply​(java.util.function.Function<? super E,​? extends T> function, java.lang.Class<?> futuretype)
      Applies a function after the result is available, using the result of this Future as input.
      <U,​V>
      IFuture<V>      		 thenCombine​(IFuture<U> other, java.util.function.BiFunction<? super E,​? super U,​? extends V> function, java.lang.Class<?> futuretype)  
      <T> IFuture<T> thenCompose​(java.util.function.Function<? super E,​IFuture<T>> function)
      The result of this future is delegated to the given (future-returning) function.
      <T> IFuture<T> thenCompose​(java.util.function.Function<? super E,​IFuture<T>> function, java.lang.Class<?> futuretype)
      The result of this future is delegated to the given (future-returning) function.
      static java.lang.RuntimeException throwException​(java.lang.Throwable t)
      Throw an exception but include the current stack trace.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • NOTIFICATIONS

        public static final java.util.Map<java.lang.Thread,​java.util.List<Tuple3<Future<?>,​IResultListener<?>,​ICommand<IResultListener<?>>>>> NOTIFICATIONS
        Notification queues for active notification threads. Notifications for a specific future/listener combination are assigned to only one thread at a time to assure notification ordering across threads and avoid duplicate notifications.

      • CALLER_QUEUED

        protected static final java.lang.String CALLER_QUEUED
        A caller is queued for suspension.
        See Also:
        Constant Field Values

      • CALLER_RESUMED

        protected static final java.lang.String CALLER_RESUMED
        A caller is resumed.
        See Also:
        Constant Field Values

      • CALLER_SUSPENDED

        protected static final java.lang.String CALLER_SUSPENDED
        A caller is suspended.
        See Also:
        Constant Field Values

      • DEBUG

        public static boolean DEBUG
        Debug flag.

      • NO_STACK_COMPACTION

        public static boolean NO_STACK_COMPACTION
        Disable Stack unfolding for easier debugging.

      • result

        protected E result
        The result.

      • exception

        protected java.lang.Exception exception
        The exception (if any).

      • resultavailable

        protected volatile boolean resultavailable
        Flag indicating if result is available.

      • callers

        protected java.util.Map<ISuspendable,​java.lang.String> callers
        The blocked callers (caller->state).

      • listeners

        protected java.util.Map<IResultListener<E>,​java.lang.Thread> listeners
        The listeners, mapped to current notification thread (if any).

      • notificount

        protected java.util.Map<IResultListener<E>,​java.lang.Integer> notificount
        The listeners, mapped to current notification count (if any).

      • creation

        protected java.lang.Exception creation
        For capturing call stack of future creation.

      • first

        protected java.lang.Exception first
        For capturing call stack of first setResult/Exception call.

      • undone

        protected boolean undone
        The undone flag.

      • notified

        protected boolean notified

    • Constructor Detail

      • Future

        public Future()
        Create a new future.

      • Future

        public Future​(E result)
        Create a future that is already done.
        Parameters:
        result - The result, if any.

      • Future

        public Future​(java.lang.Exception exception)
        Create a future that is already failed.
        Parameters:
        exception - The exception.

    • Method Detail

      • getEmptyFuture

        public static <T> IFuture<T> getEmptyFuture()
        Get the empty future of some type.
        Returns:
        The empty future.

      • isDone

        public boolean isDone()
        Test if done, i.e. result is available.
        Specified by:
        isDone in interface IFuture<E>
        Returns:
        True, if done.

      • getException

        public java.lang.Exception getException()
        Get the exception, if any.
        Specified by:
        getException in interface IFuture<E>
        Returns:
        The exception, if any, or null if the future is not yet done or succeeded without exception.

      • get

        public E get​(ThreadSuspendable sus)
        Deprecated.
        - From 3.0. Use the version without suspendable. Will NOT use the suspendable given as parameter. Get the result - blocking call.
        Specified by:
        get in interface IFuture<E>
        Returns:
        The future result.

      • get

        public E get()
        Get the result - blocking call.
        Specified by:
        get in interface IFuture<E>
        Returns:
        The future result.

      • get

        public E get​(boolean realtime)
        Get the result - blocking call.
        Specified by:
        get in interface IFuture<E>
        Parameters:
        realtime - Flag, if wait should be realtime (in constrast to simulation time).
        Returns:
        The future result.

      • get

        public E get​(long timeout)
        Get the result - blocking call.
        Specified by:
        get in interface IFuture<E>
        Parameters:
        timeout - The timeout in millis.
        Returns:
        The future result.

      • get

        public E get​(long timeout,
             boolean realtime)
        Get the result - blocking call.
        Specified by:
        get in interface IFuture<E>
        Parameters:
        timeout - The timeout in millis.
        realtime - Flag if timeout is realtime (in contrast to simulation time).
        Returns:
        The future result.

      • throwException

        public static java.lang.RuntimeException throwException​(java.lang.Throwable t)
        Throw an exception but include the current stack trace.

      • doSetException

        protected boolean doSetException​(java.lang.Exception exception,
                                 boolean undone)
        Set the exception (internal implementation for normal and if-undone).

      • setException

        public void setException​(java.lang.Exception exception)
        Set the exception. Listener notifications occur on calling thread of this method.
        Parameters:
        exception - The exception.

      • setExceptionIfUndone

        public boolean setExceptionIfUndone​(java.lang.Exception exception)
        Set the exception. Listener notifications occur on calling thread of this method.
        Parameters:
        exception - The exception.

      • setResult

        public void setResult​(E result)
        Set the result. Listener notifications occur on calling thread of this method.
        Parameters:
        result - The result.

      • setResultIfUndone

        public boolean setResultIfUndone​(E result)
        Set the result. Listener notifications occur on calling thread of this method.
        Parameters:
        result - The result.
        Returns:
        True if result was set.

      • doSetResult

        protected boolean doSetResult​(E result,
                              boolean undone)
        Set the result without notifying listeners.

      • isNotified

        public boolean isNotified()
        Was the result/exception (scheduled to be) notified to some listener/blocked caller?

      • resume

        protected void resume()
        Resume after result or exception has been set.

      • abortGet

        public void abortGet​(ISuspendable caller)
        Abort a blocking get call.

      • scheduleNotification

        protected boolean scheduleNotification​(IFilter<IResultListener<E>> filter,
                                       ICommand<IResultListener<E>> command)
        Schedule a notification for selected listeners. Safe to be called from synchronized block. Assigns notifications to existing notification thread (if any) for each giving listener or selects the current thread as notification thread when a listener does not yet have an assigned notification thread.
        Parameters:
        filter - Optional filter to select only specific listener (e.g. for forward commands). Otherwise uses all listeners.
        command - The notification command to execute for each selected listener.
        Returns:
        True, when at least one listener notification was scheduled.

      • scheduleNotification

        protected void scheduleNotification​(IResultListener<E> listener,
                                    ICommand<IResultListener<E>> command)
        Schedule a listener notification for a specific listener to be executed outside the synchronized block. Can be called from synchronized block; after exiting the synchronized block, scheduled notifications should be executed (@see startScheduledNotifications()).
        Parameters:
        listener - The listener to notify.
        command - The notification command to execute for the listener.

      • startScheduledNotifications

        protected static final void startScheduledNotifications()
        Start scheduled listener notifications using stack compaction, if desired. Must not be called from synchronized block. Can be called from any thread and checks if thread is chosen one.

      • doStartScheduledNotifications

        protected static <T> void doStartScheduledNotifications()
        Start scheduled listener notifications. Must not be called from synchronized block. Is not called recursively if stack compaction is enabled.

      • doAddResultListener

        protected boolean doAddResultListener​(IResultListener<E> listener)
        Add a listener and check if it should be notified immediately due to the future already being finished before add. Safe to be called in synchronized block.

      • getNotificationCommand

        protected ICommand<IResultListener<E>> getNotificationCommand()
        Get the notification command.

      • sendForwardCommand

        public void sendForwardCommand​(java.lang.Object command)
        Send a (forward) command to the listeners.
        Specified by:
        sendForwardCommand in interface IForwardCommandFuture
        Parameters:
        command - The command.

      • hasResultListener

        public boolean hasResultListener()
        Check, if the future has at least one listener.

      • then

        public IFuture<? extends E> then​(java.util.function.Consumer<? super E> function)
        Description copied from interface: IFuture
        Applies a function after the result is available, using the result of this Future as input.
        Specified by:
        then in interface IFuture<E>
        Parameters:
        function - Function that takes the result of this future as input and delivers t.
        Returns:
        Future of the result after the function has been applied.

      • thenApply

        public <T> IFuture<T> thenApply​(java.util.function.Function<? super E,​? extends T> function)
        Description copied from interface: IFuture
        Applies a function after the result is available, using the result of this Future as input.
        Specified by:
        thenApply in interface IFuture<E>
        Parameters:
        function - Function that takes the result of this future as input and delivers t.
        Returns:
        Future of the result after the function has been applied.

      • thenApply

        public <T> IFuture<T> thenApply​(java.util.function.Function<? super E,​? extends T> function,
                                java.lang.Class<?> futuretype)
        Description copied from interface: IFuture
        Applies a function after the result is available, using the result of this Future as input.
        Specified by:
        thenApply in interface IFuture<E>
        Parameters:
        function - Function that takes the result of this future as input and delivers t.
        futuretype - The type of the return future.
        Returns:
        Future of the result after the function has been applied.

      • thenCompose

        public <T> IFuture<T> thenCompose​(java.util.function.Function<? super E,​IFuture<T>> function)
        Description copied from interface: IFuture
        The result of this future is delegated to the given (future-returning) function. The result of the function will be available in the returned future.
        Specified by:
        thenCompose in interface IFuture<E>
        Parameters:
        function - Function that takes the result of this future as input and delivers future(t).
        Returns:
        Future of the result of the second async call.

      • thenCompose

        public <T> IFuture<T> thenCompose​(java.util.function.Function<? super E,​IFuture<T>> function,
                                  java.lang.Class<?> futuretype)
        Description copied from interface: IFuture
        The result of this future is delegated to the given (future-returning) function. The result of the function will be available in the returned future.
        Specified by:
        thenCompose in interface IFuture<E>
        Parameters:
        function - Function that takes the result of this future as input and delivers future(t).
        futuretype - The type of the return future. If null, a default future is created.
        Returns:
        Future of the result of the second async call.

      • thenAccept

        public IFuture<java.lang.Void> thenAccept​(java.util.function.Consumer<? super E> consumer)

      • thenAccept

        public IFuture<java.lang.Void> thenAccept​(java.util.function.Consumer<? super E> consumer,
                                          java.lang.Class<?> futuretype)

      • thenCombine

        public <U,​V> IFuture<V> thenCombine​(IFuture<U> other,
                                          java.util.function.BiFunction<? super E,​? super U,​? extends V> function,
                                          java.lang.Class<?> futuretype)

      • delegate

        public void delegate​(Future<E> delegate)
        Deprecated.
        Use delegateTo.
        Delegate the result and exception to another future. Short form for adding a delegation listener.
        Specified by:
        delegate in interface IFuture<E>
        Parameters:
        delegate - The other future.

      • delegateTo

        public void delegateTo​(Future<E> target)
        Forward the result and exception to another future. Short form for adding a delegation listener.
        Specified by:
        delegateTo in interface IFuture<E>
        Parameters:
        target - The target future.

      • delegateFrom

        public void delegateFrom​(IFuture<E> source)
        Delegate the result and exception from another future.
        Parameters:
        source - The source future.

      • catchEx

        public <T> IFuture<E> catchEx​(Future<T> delegate)
        Called on exception.
        Specified by:
        catchEx in interface IFuture<E>
        Parameters:
        delegate - The future the exception will be delegated to.

      • catchEx

        public IFuture<E> catchEx​(java.util.function.Consumer<? super java.lang.Exception> consumer)
        Called on exception.
        Specified by:
        catchEx in interface IFuture<E>
        Parameters:
        delegate - The future the exception will be delegated to.

      • catchEx

        public IFuture<E> catchEx​(java.util.function.Consumer<? super java.lang.Exception> consumer,
                          java.lang.Class<?> futuretype)
        Called on exception.
        Specified by:
        catchEx in interface IFuture<E>
        Parameters:
        consumer - The function called with the exception.
        futuretype - The function called with the exception.

      • getFuture

        public <T> Future<T> getFuture​(java.lang.Class<?> futuretype)
        Sequential execution of async methods via implicit delegation.
        Parameters:
        futuretype - The type of the result future (cannot be automatically determined).
        Returns:
        Future of the result of the second async call.