org.threadly.concurrent.future

Class SettableListenableFuture<T>

java.lang.Object

org.threadly.concurrent.future.SettableListenableFuture<T>

Type Parameters:

T - The result object type returned by this future

All Implemented Interfaces:

java.util.concurrent.Future<T>, FutureCallback<T>, ListenableFuture<T>

public class SettableListenableFuture<T>
extends java.lang.Object
implements ListenableFuture<T>, FutureCallback<T>

This class is designed to be a helper when returning a single result asynchronously. This is particularly useful if this result is produced over multiple threads (and thus the scheduler returned future is not useful).

Since:

1.2.0

Nested Class Summary

Nested classes/interfaces inherited from interface org.threadly.concurrent.future.ListenableFuture

ListenableFuture.ListenerOptimizationStrategy

Constructor Summary

Constructors

Constructor and Description
SettableListenableFuture() Constructs a new SettableListenableFuture.
SettableListenableFuture(boolean throwIfAlreadyComplete) Constructs a new SettableListenableFuture.

Method Summary

Modifier and Type	Method and Description
void	addListener(java.lang.Runnable listener, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimize) Add a listener to be called once the future has completed.
boolean	cancel(boolean interruptThread)
void	clearResult() Clears the stored result from this set future.
T	get()
T	get(long timeout, java.util.concurrent.TimeUnit unit)
void	handleFailure(java.lang.Throwable t) This call defers to setFailure(Throwable).
void	handleResult(T result) This call defers to setResult(Object).
boolean	isCancelled()
boolean	isDone()
boolean	setFailure(java.lang.Throwable failure) Call to indicate this future is done, and provide the occurred failure.
boolean	setResult(T result) Call to indicate this future is done, and provide the given result.
void	setRunningThread(java.lang.Thread thread) Optional call to set the thread internally that will be generating the result for this future.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.threadly.concurrent.future.ListenableFuture

addCallback, addCallback, addCallback, addListener, addListener, flatMap, flatMap, flatMap, map, map, map, throwMap, throwMap, throwMap

Constructor Detail

SettableListenableFuture

public SettableListenableFuture()

Constructs a new SettableListenableFuture. You can return this immediately and provide a result to the object later when it is ready.

This defaults in the behavior since version 1.2.0 where if the future has completed (either by cancel(boolean), setResult(Object), or setFailure(Throwable)), any additional attempts to setResult(Object) or setFailure(Throwable) will result in a IllegalStateException being thrown.

SettableListenableFuture

public SettableListenableFuture(boolean throwIfAlreadyComplete)

Constructs a new SettableListenableFuture. You can return this immediately and provide a result to the object later when it is ready.

This constructor allows you to control the behavior when results are attempt to be set after the future has already completed (either by cancel(boolean), setResult(Object), or setFailure(Throwable)).

If true, any additional attempts to setResult(Object) or setFailure(Throwable) will result in a IllegalStateException being thrown.

If false, additional attempts to set a result will just be silently ignored.

Parameters:

throwIfAlreadyComplete - Defines the behavior when result or failure is set on a completed future

Method Detail

addListener

public void addListener(java.lang.Runnable listener,
                        java.util.concurrent.Executor executor,
                        ListenableFuture.ListenerOptimizationStrategy optimize)

Description copied from interface: ListenableFuture

Add a listener to be called once the future has completed. If the future has already finished, this will be called immediately.

If the provided Executor is null, the listener will execute on the thread which computed the original future (once it is done). If the future has already completed, the listener will execute immediately on the thread which is adding the listener.

Caution should be used when choosing to optimize the listener execution. If the listener is complex, or wanting to be run concurrent, this optimization could prevent that. In addition it will prevent other listeners from potentially being invoked until it completes. However if the listener is small / fast, this can provide significant performance gains. It should also be known that not all ListenableFuture implementations may be able to do such an optimization. Please see ListenableFuture.ListenerOptimizationStrategy javadocs for more specific details of what optimizations are available.

Specified by:

addListener in interface ListenableFuture<T>

Parameters:

listener - the listener to run when the computation is complete

executor - Executor the listener should be ran on, or null

optimize - true to avoid listener queuing for execution if already on the desired pool

handleResult

public void handleResult(T result)

This call defers to setResult(Object). It is implemented so that you can construct this, return it immediately, but only later provide this as a callback to another ListenableFuture implementation.

This should never be invoked by the implementor, this should only be invoked by other ListenableFuture's.

If this is being used to chain together ListenableFuture's, setResult(Object)/setFailure(Throwable) should never be called manually (or an exception will occur).

Specified by:

handleResult in interface FutureCallback<T>

Parameters:

result - Result object to provide to the future to be returned from get() call

handleFailure

public void handleFailure(java.lang.Throwable t)

This call defers to setFailure(Throwable). It is implemented so that you can construct this, return it immediately, but only later provide this as a callback to another ListenableFuture implementation.

This should never be invoked by the implementor, this should only be invoked by other ListenableFuture's.

If this is being used to chain together ListenableFuture's, setResult(Object)/setFailure(Throwable) should never be called manually (or an exception will occur).

Specified by:

handleFailure in interface FutureCallback<T>

Parameters:

t - Throwable to be provided as the cause from the ExecutionException thrown from get() call

setResult

public boolean setResult(T result)

Call to indicate this future is done, and provide the given result. It is expected that only this or setFailure(Throwable) are called.

If future has already completed and constructed with SettableListenableFuture() or true provided to SettableListenableFuture(boolean) this will throw an IllegalStateException. If complete but constructed with a false this result will be ignored.

Parameters:

result - result to provide for get() call, can be null

Returns:

true if the result was set (ie future did not complete in failure or cancel}

setFailure

public boolean setFailure(java.lang.Throwable failure)

Call to indicate this future is done, and provide the occurred failure. It is expected that only this or setResult(Object) are called, and only called once. If the provided failure is null, a new Exception will be created so that something is always provided in the ExecutionException on calls to get().

If future has already completed and constructed with SettableListenableFuture() or true provided to SettableListenableFuture(boolean) this will throw an IllegalStateException. If complete but constructed with a false this failure result will be ignored.

Parameters:

failure - Throwable that caused failure during computation.

Returns:

true if the failure was set (ie future did not complete with result or cancel}

setRunningThread

public void setRunningThread(java.lang.Thread thread)

Optional call to set the thread internally that will be generating the result for this future. Setting this thread allows it so that if a cancel(boolean) call is invoked with true, we can send an interrupt to this thread.

The reference to this thread will be cleared after this future has completed (thus allowing it to be garbage collected).

Parameters:

thread - Thread that is generating the result for this future

cancel

public boolean cancel(boolean interruptThread)

Specified by:

cancel in interface java.util.concurrent.Future<T>

isCancelled

public boolean isCancelled()

Specified by:

isCancelled in interface java.util.concurrent.Future<T>

clearResult

public void clearResult()

Clears the stored result from this set future. This allows the result to be available for garbage collection. After this call, future calls to get() will throw an IllegalStateException. So it is critical that this is only called after you are sure no future calls to get the result on this future will be attempted.

The design of this is so that if you want to chain ListenableFuture's together, you can clear the results of old ones after their result has been consumed. This is really only useful in very specific instances.

isDone

public boolean isDone()

Specified by:

isDone in interface java.util.concurrent.Future<T>

get

public T get()
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException

Specified by:

get in interface java.util.concurrent.Future<T>

Throws:

java.lang.InterruptedException

java.util.concurrent.ExecutionException

get

public T get(long timeout,
             java.util.concurrent.TimeUnit unit)
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException,
             java.util.concurrent.TimeoutException

Specified by:

get in interface java.util.concurrent.Future<T>

Throws:

java.lang.InterruptedException

java.util.concurrent.ExecutionException

java.util.concurrent.TimeoutException