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
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
-
Nested Class Summary
Nested classes/interfaces inherited from interface jadex.future.IForwardCommandFuture
IForwardCommandFuture.Type
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected static final String
A caller is queued for suspension.protected static final String
A caller is resumed.protected static final String
A caller is suspended.protected Map
<ISuspendable, String[]> The blocked callers (caller->state).protected Exception
For capturing call stack of future creation.static boolean
Debug flag.protected Exception
The exception (if any).protected Exception
For capturing call stack of first setResult/Exception call.protected Map
<IResultListener<E>, Thread> The listeners, mapped to current notification thread (if any).static boolean
Disable Stack unfolding for easier debugging.static final long
Constant for no timeout.protected jadex.common.ICommand
<IResultListener<E>> static final Map
<Thread, List<jadex.common.Tuple3<Future<?>, IResultListener<?>, jadex.common.ICommand<IResultListener<?>>>>> Notification queues for active notification threads.protected Map
<IResultListener<E>, Integer> The listeners, mapped to current notification count (if any).protected boolean
protected E
The result.protected boolean
Flag indicating if result is available.protected boolean
The undone flag.static final long
Constant for unset. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
abortGet
(ISuspendable caller) Abort a blocking get call.void
addResultListener
(IResultListener<E> listener) Add a result listener.Called on exception.Called on exception.Called on exception.void
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
(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
Start scheduled listener notifications.protected void
executeNotification
(IResultListener<E> listener, jadex.common.ICommand<IResultListener<E>> command) Execute a notification.get()
Get the result - blocking call.get
(boolean realtime) Get the result - blocking call.get
(long timeout) Get the result - blocking call.get
(long timeout, boolean realtime) Get the result - blocking call.get
(ThreadSuspendable sus) Deprecated.- From 3.0.static <T> IFuture
<T> Get the empty future of some type.Get the exception, if any.static <T> Future
<T> Get the matching future object to a future (interface) type.protected jadex.common.ICommand
<IResultListener<E>> Get the notification command.boolean
Check, if the future has at least one listener.boolean
isDone()
Test if done, i.e.boolean
Was the result/exception (scheduled to be) notified to some listener/blocked caller?Print an exception.protected void
resume()
Resume after result or exception has been set.protected boolean
scheduleNotification
(jadex.common.IFilter<IResultListener<E>> filter, jadex.common.ICommand<IResultListener<E>> command) Schedule a notification for selected listeners.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.void
sendForwardCommand
(Object command) Send a (forward) command to the listeners.void
setException
(Exception exception) Set the exception.boolean
setExceptionIfUndone
(Exception exception) Set the exception.void
Set the result.boolean
setResultIfUndone
(E result) Set the result.protected static final void
Start scheduled listener notifications using stack compaction, if desired.Applies a function after the result is available, using the result of this Future as input.thenAccept
(Consumer<? super E> consumer) thenAccept
(Consumer<? super E> consumer, Class<?> futuretype) <T> IFuture
<T> Applies a function after the result is available, using the result of this Future as input.<T> IFuture
<T> Applies a function after the result is available, using the result of this Future as input.<U,
V> IFuture <V> thenCombine
(IFuture<U> other, BiFunction<? super E, ? super U, ? extends V> function, Class<?> futuretype) <T> IFuture
<T> thenCompose
(Function<? super E, IFuture<T>> function) The result of this future is delegated to the given (future-returning) function.<T> IFuture
<T> thenCompose
(Function<? super E, IFuture<T>> function, Class<?> futuretype) The result of this future is delegated to the given (future-returning) function.static RuntimeException
Throw an exception but include the current stack trace.
-
Field Details
-
NOTIFICATIONS
public static final Map<Thread,List<jadex.common.Tuple3<Future<?>, NOTIFICATIONSIResultListener<?>, jadex.common.ICommand<IResultListener<?>>>>> 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
A caller is queued for suspension.- See Also:
-
CALLER_RESUMED
A caller is resumed.- See Also:
-
CALLER_SUSPENDED
A caller is suspended.- See Also:
-
DEBUG
public static boolean DEBUGDebug flag. -
NO_STACK_COMPACTION
public static boolean NO_STACK_COMPACTIONDisable Stack unfolding for easier debugging. -
NONE
public static final long NONEConstant for no timeout.- See Also:
-
UNSET
public static final long UNSETConstant for unset.- See Also:
-
result
The result. -
exception
The exception (if any). -
resultavailable
protected volatile boolean resultavailableFlag indicating if result is available. -
callers
The blocked callers (caller->state). -
listeners
The listeners, mapped to current notification thread (if any). -
notificount
The listeners, mapped to current notification count (if any). -
creation
For capturing call stack of future creation. -
first
For capturing call stack of first setResult/Exception call. -
undone
protected boolean undoneThe undone flag. -
notified
protected boolean notified -
notcommand
-
-
Constructor Details
-
Future
public Future()Create a new future. -
Future
Create a future that is already done.- Parameters:
result
- The result, if any.
-
Future
Create a future that is already failed.- Parameters:
exception
- The exception.
-
-
Method Details
-
getEmptyFuture
Get the empty future of some type.- Returns:
- The empty future.
-
isDone
public boolean isDone()Test if done, i.e. result is available. -
getException
Get the exception, if any.- Specified by:
getException
in interfaceIFuture<E>
- Returns:
- The exception, if any, or null if the future is not yet done or succeeded without exception.
-
get
Deprecated.- From 3.0. Use the version without suspendable. Will NOT use the suspendable given as parameter. Get the result - blocking call. -
get
Get the result - blocking call. -
get
Get the result - blocking call. -
get
Get the result - blocking call. -
get
Get the result - blocking call. -
throwException
Throw an exception but include the current stack trace.- Parameters:
t
- The throwable.- Returns:
- The runtime exception.
-
doSetException
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
Set the exception. Listener notifications occur on calling thread of this method.- Parameters:
exception
- The exception.
-
setExceptionIfUndone
Set the exception. Listener notifications occur on calling thread of this method.- Parameters:
exception
- The exception.
-
setResult
Set the result. Listener notifications occur on calling thread of this method.- Parameters:
result
- The result.
-
setResultIfUndone
Set the result. Listener notifications occur on calling thread of this method.- Parameters:
result
- The result.- Returns:
- True if result was set.
-
doSetResult
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
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
Add a result listener.- Specified by:
addResultListener
in interfaceIFuture<E>
- Parameters:
listener
- The listener.
-
doAddResultListener
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
Get the notification command. -
sendForwardCommand
Send a (forward) command to the listeners.- Specified by:
sendForwardCommand
in interfaceIForwardCommandFuture
- Parameters:
command
- The command.
-
hasResultListener
public boolean hasResultListener()Check, if the future has at least one listener. -
then
Description copied from interface:IFuture
Applies a function after the result is available, using the result of this Future as input. -
thenApply
Description copied from interface:IFuture
Applies a function after the result is available, using the result of this Future as input. -
thenApply
Description copied from interface:IFuture
Applies a function after the result is available, using the result of this Future as input. -
thenCompose
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 interfaceIFuture<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
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 interfaceIFuture<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
-
thenAccept
-
thenCombine
public <U,V> IFuture<V> thenCombine(IFuture<U> other, BiFunction<? super E, ? super U, ? extends V> function, Class<?> futuretype) -
delegate
Deprecated.Use delegateTo.Delegate the result and exception to another future. Short form for adding a delegation listener. -
delegateTo
Forward the result and exception to another future. Short form for adding a delegation listener.- Specified by:
delegateTo
in interfaceIFuture<E>
- Parameters:
target
- The target future.
-
delegateFrom
Delegate the result and exception from another future.- Parameters:
source
- The source future.
-
catchEx
Called on exception. -
catchEx
Called on exception. -
catchEx
Called on exception. -
printOnEx
Print an exception. -
getFuture
Get the matching future object to a future (interface) type.
-