Package jadex.commons.future

Class Future<E>

    • 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.

    • 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.

      • 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.

      • 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​(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​(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​(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​(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​(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​(Consumer<? super E> consumer)

      • thenAccept

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

      • thenCombine

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

      • catchErr

        public <T> void catchErr​(Future<T> delegate)
        Sequential execution of async methods via implicit delegation.
        Specified by:
        catchErr in interface IFuture<E>
        Parameters:
        function - Function that takes the result of this future as input and delivers future(t).
        ret - The

      • catchErr

        public IFuture<E> catchErr​(Consumer<? super java.lang.Exception> consumer,
                           java.lang.Class<?> futuretype)
        Specified by:
        catchErr in interface IFuture<E>

      • 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.