Package jadex.future

Class Future<E>

java.lang.Object
jadex.future.Future<E>
All Implemented Interfaces:
IForwardCommandFuture, IFuture<E>, Supplier<E>
Direct Known Subclasses:
IntermediateFuture, TerminableDelegationFuture, TerminableFuture
public class Future<E> extends Object implements IFuture<E>, IForwardCommandFuture
Future that includes mechanisms for callback notification. This allows a caller to decide if a) a blocking call to get() should be used b) a callback shall be invoked

  • Field Details

    • NOTIFICATIONS

      public static final Map<Thread,List<jadex.common.Tuple3<Future<?>,IResultListener<?>,jadex.common.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 String CALLER_QUEUED
      A caller is queued for suspension.
      See Also:

    • CALLER_RESUMED

      protected static final String CALLER_RESUMED
      A caller is resumed.
      See Also:

    • CALLER_SUSPENDED

      protected static final String CALLER_SUSPENDED
      A caller is suspended.
      See Also:

    • DEBUG

      public static boolean DEBUG
      Debug flag.

    • NO_STACK_COMPACTION

      public static boolean NO_STACK_COMPACTION
      Disable Stack unfolding for easier debugging.

    • NONE

      public static final long NONE
      Constant for no timeout.
      See Also:

    • UNSET

      public static final long UNSET
      Constant for unset.
      See Also:

    • result

      protected E result
      The result.

    • exception

      protected Exception exception
      The exception (if any).

    • resultavailable

      protected volatile boolean resultavailable
      Flag indicating if result is available.

    • callers

      protected Map<ISuspendable,String[]> callers
      The blocked callers (caller->state).

    • listeners

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

    • notificount

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

    • creation

      protected Exception creation
      For capturing call stack of future creation.

    • first

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

    • undone

      protected boolean undone
      The undone flag.

    • notified

      protected boolean notified

    • notcommand

      protected jadex.common.ICommand<IResultListener<E>> notcommand

  • Constructor Details

    • 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(Exception exception)
      Create a future that is already failed.
      Parameters:
      exception - The exception.

  • Method Details

    • 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 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>
      Specified by:
      get in interface Supplier<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 RuntimeException throwException(Throwable t)
      Throw an exception but include the current stack trace.
      Parameters:
      t - The throwable.
      Returns:
      The runtime exception.

    • doSetException

      protected boolean doSetException(Exception exception, boolean undone)
      Set the exception (internal implementation for normal and if-undone).
      Parameters:
      exception - The exception.
      undone - The undone flag.
      Returns:
      True, if exception was set.

    • setException

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

    • setExceptionIfUndone

      public boolean setExceptionIfUndone(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.
      Parameters:
      result - The result.
      undone - The undone flag.
      Returns:
      True, if exception was set.

    • isNotified

      public boolean isNotified()
      Was the result/exception (scheduled to be) notified to some listener/blocked caller?
      Returns:
      True, if notified.

    • resume

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

    • abortGet

      public void abortGet(ISuspendable caller)
      Abort a blocking get call.
      Parameters:
      caller - The caller

    • scheduleNotification

      protected boolean scheduleNotification(jadex.common.IFilter<IResultListener<E>> filter, jadex.common.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, jadex.common.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.

    • executeNotification

      protected void executeNotification(IResultListener<E> listener, jadex.common.ICommand<IResultListener<E>> command)
      Execute a notification. Override for scheduling on other threads.

    • addResultListener

      public void addResultListener(IResultListener<E> listener)
      Add a result listener.
      Specified by:
      addResultListener in interface IFuture<E>
      Parameters:
      listener - The listener.

    • 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 jadex.common.ICommand<IResultListener<E>> getNotificationCommand()
      Get the notification command.

    • sendForwardCommand

      public void sendForwardCommand(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, 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, 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<Void> thenAccept(Consumer<? super E> consumer)

    • thenAccept

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

    • thenCombine

      public <U, V> IFuture<V> thenCombine(IFuture<U> other, BiFunction<? super E,? super U,? extends V> function, 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(Consumer<? super Exception> consumer)
      Called on exception.
      Specified by:
      catchEx in interface IFuture<E>
      Parameters:
      consumer - The consumer the exception will be delegated to.

    • catchEx

      public IFuture<E> catchEx(Consumer<? super Exception> consumer, 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.

    • printOnEx

      public IFuture<E> printOnEx()
      Print an exception.
      Specified by:
      printOnEx in interface IFuture<E>

    • getFuture

      public static <T> Future<T> getFuture(Class<?> clazz)
      Get the matching future object to a future (interface) type.