net.lecousin.framework.concurrent.async

Interface IAsync<TError extends Exception>

Type Parameters:

TError - type of exception it may raise.

All Superinterfaces:

Cancellable

All Known Implementing Classes:

AbstractLock, Async, AsyncSupplier, JoinPoint, LockPoint, MutualExclusion, Task.Output, WaitingDataQueueSynchronizationPoint

public interface IAsync<TError extends Exception>
extends Cancellable

Base interface for an asynchronous unit.

An asynchronous unit can have 4 states:

• Blocked: this is the first state, until something happens (resource available, task done...)
• Unblocked with error: when an error occurs (while processing the task, if the waited resource cannot be obtained, or if the underlying process was itself waiting for an asynchronous unit that raised an error)
• Unblocked with cancellation: when explicitly cancelled or because the underlying process was itself waiting for an asynchronous unit that has been cancelled.
• Unblocked with success

The state can be consulted using methods isDone(), hasError() and Cancellable.isCancelled().

Listeners can be added to be called when the asynchronous unit is unblocked. The order listeners are called is not guaranteed, especially because if a listener is added while the previously registered listeners are called, the new listener will be immediately executed by the calling thread, without waiting for other listeners to finish.

Method Summary

Modifier and Type	Method and Description
void	block(long timeout) Pause the current thread to wait for this asynchronous unit to be unblocked.
default void	blockException(long timeout) Pause the current thread to wait for this asynchronous unit to be unblocked, and if it has an error it is thrown.
default void	blockPause(long logWarningAfterMillis) Really block, using wait method (used by threading system to know when a thread can be resumed).
boolean	blockPauseCondition() Return true if blockPause should still block.
default void	blockThrow(long timeout) Pause the current thread to wait for this synchronization point to be unblocked.
void	error(TError error) Unblock with an error.
default boolean	forwardIfNotSuccessful(IAsync<TError> sp) If this asynchronous unit is not successful, forward the result to the given one (this object MUST be done).
Collection<?>	getAllListeners() Return a collection with all listeners, only for debugging purposes.
TError	getError() Return the error.
boolean	hasError() Return true if unblocked because of an error.
boolean	isDone() Return true if unblocked (success or cancelled).
default boolean	isSuccessful() Return true if unblocked with success: it must be unblocked, without error, and without a cancel event.
default void	logListenerError(Logger log, Object listener, Throwable error) Log an error thrown by a listener.
default void	onCancel(Consumer<CancelException> listener) Call the given listener, only when done due to cancellation.
default void	onDone(Async<TError> sp) Transfer the result of this asynchronous unit to the given one: unblock it on success, call error method on error, or call cancel method on cancellation.
default <TError2 extends Exception> void	onDone(Async<TError2> sp, Function<TError,TError2> errorConverter) Transfer the result of this asynchronous unit to the given one: unblock it on success, call error method on error, or call cancel method on cancellation.
default <T> void	onDone(AsyncSupplier<T,TError> sp, Supplier<T> resultSupplier) Unblock the given AsyncSupplier, or forward the error or cancellation.
void	onDone(Runnable listener) Call listener when unblocked (whatever the result is successful, has error or is cancelled).
default void	onDone(Runnable onReady, Consumer<TError> onError, Consumer<CancelException> onCancel) Call listeners when unblocked.
default void	onDone(Runnable onReady, IAsync<TError> onErrorOrCancel) Call listener when unblocked, or forward error/cancellation to onErrorOrCancel.
default <TError2 extends Exception> void	onDone(Runnable onReady, IAsync<TError2> onErrorOrCancel, Function<TError,TError2> errorConverter) Call listener when unblocked, or forward error/cancellation to onErrorOrCancel.
default void	onError(Consumer<TError> listener) Call the given listener, only when done with an error.
default void	onErrorOrCancel(Runnable runnable) Call the given runnable on error or cancellation.
default void	onSuccess(Runnable listener) Call the given listener, only when done without error or cancellation.
default boolean	thenDoOrStart(Runnable runnable, String taskDescription, byte taskPriority) Call runnable immediately (in current thread) if done, or start a CPU task on done.
default boolean	thenDoOrStart(Runnable runnable, String taskDescription, byte taskPriority, IAsync<TError> onErrorOrCancel) Call runnable immediately (in current thread) if done, or start a CPU task on done.
default <TError2 extends Exception> boolean	thenDoOrStart(Runnable runnable, String taskDescription, byte taskPriority, IAsync<TError2> onErrorOrCancel, Function<TError,TError2> errorConverter) Call runnable immediately (in current thread) if done, or start a CPU task on done.
default void	thenStart(String description, byte priority, Runnable task, boolean evenIfErrorOrCancel) Start the given task when this asynchronous unit is unblocked.
default void	thenStart(String description, byte priority, Runnable task, IAsync<TError> onErrorOrCancel) Start the given task when this synchronization point is successfully unblocked, else the error or cancel event are forwarded to the given synchronization point.
default void	thenStart(Task<?,? extends Exception> task, boolean evenIfErrorOrCancel) Start the given task when this asynchronous unit is unblocked.
default void	thenStart(Task<?,? extends Exception> task, IAsync<TError> onErrorOrCancel) Start the given task when this asynchronous unit is successfully unblocked, else the error or cancel event are forwarded to the given asynchronous unit.
default <TError2 extends Exception> void	thenStart(Task<?,? extends Exception> task, IAsync<TError2> onErrorOrCancel, Function<TError,TError2> errorConverter) Start the given task when this synchronization point is successfully unblocked, else the error or cancel event are forwarded to the given synchronization point.
default void	thenStart(Task<?,? extends Exception> task, Runnable onErrorOrCancel) Start the given task when this asynchronous unit is unblocked.
default AsyncSupplier<Void,TError>	toAsyncSupplier() Convert this synchronization point into an AsyncWork with Void result.

Methods inherited from interface net.lecousin.framework.concurrent.async.Cancellable

cancel, getCancelEvent, isCancelled

Method Detail

isDone

boolean isDone()

Return true if unblocked (success or cancelled).

hasError

boolean hasError()

Return true if unblocked because of an error.

error

void error(TError error)

Unblock with an error.

getError

TError getError()

Return the error.

isSuccessful

default boolean isSuccessful()

Return true if unblocked with success: it must be unblocked, without error, and without a cancel event.

block

void block(long timeout)

Pause the current thread to wait for this asynchronous unit to be unblocked.

blockException

default void blockException(long timeout)
                     throws TError extends Exception

Pause the current thread to wait for this asynchronous unit to be unblocked, and if it has an error it is thrown.

Throws:

TError extends Exception

blockThrow

default void blockThrow(long timeout)
                 throws TError extends Exception,
                        CancelException

Pause the current thread to wait for this synchronization point to be unblocked. If it has an error or a cancellation it is thrown.

Throws:

TError extends Exception

CancelException

blockPause

default void blockPause(long logWarningAfterMillis)

Really block, using wait method (used by threading system to know when a thread can be resumed).

blockPauseCondition

boolean blockPauseCondition()

Return true if blockPause should still block.

onSuccess

default void onSuccess(Runnable listener)

Call the given listener, only when done without error or cancellation.

onError

default void onError(Consumer<TError> listener)

Call the given listener, only when done with an error.

onCancel

default void onCancel(Consumer<CancelException> listener)

Call the given listener, only when done due to cancellation.

onErrorOrCancel

default void onErrorOrCancel(Runnable runnable)

Call the given runnable on error or cancellation.

onDone

void onDone(Runnable listener)

Call listener when unblocked (whatever the result is successful, has error or is cancelled).

onDone

default void onDone(Async<TError> sp)

Transfer the result of this asynchronous unit to the given one: unblock it on success, call error method on error, or call cancel method on cancellation.

onDone

default <TError2 extends Exception> void onDone(Async<TError2> sp,
                                                Function<TError,TError2> errorConverter)

Transfer the result of this asynchronous unit to the given one: unblock it on success, call error method on error, or call cancel method on cancellation.

onDone

default <T> void onDone(AsyncSupplier<T,TError> sp,
                        Supplier<T> resultSupplier)

Unblock the given AsyncSupplier, or forward the error or cancellation.

onDone

default void onDone(Runnable onReady,
                    Consumer<TError> onError,
                    Consumer<CancelException> onCancel)

Call listeners when unblocked.

onDone

default void onDone(Runnable onReady,
                    IAsync<TError> onErrorOrCancel)

Call listener when unblocked, or forward error/cancellation to onErrorOrCancel.

onDone

default <TError2 extends Exception> void onDone(Runnable onReady,
                                                IAsync<TError2> onErrorOrCancel,
                                                Function<TError,TError2> errorConverter)

Call listener when unblocked, or forward error/cancellation to onErrorOrCancel.

forwardIfNotSuccessful

default boolean forwardIfNotSuccessful(IAsync<TError> sp)

If this asynchronous unit is not successful, forward the result to the given one (this object MUST be done).

thenStart

default void thenStart(Task<?,? extends Exception> task,
                       boolean evenIfErrorOrCancel)

Start the given task when this asynchronous unit is unblocked.

thenStart

default void thenStart(String description,
                       byte priority,
                       Runnable task,
                       boolean evenIfErrorOrCancel)

Start the given task when this asynchronous unit is unblocked.

thenStart

default void thenStart(Task<?,? extends Exception> task,
                       Runnable onErrorOrCancel)

Start the given task when this asynchronous unit is unblocked.

thenStart

default void thenStart(Task<?,? extends Exception> task,
                       IAsync<TError> onErrorOrCancel)

Start the given task when this asynchronous unit is successfully unblocked, else the error or cancel event are forwarded to the given asynchronous unit.

thenStart

default <TError2 extends Exception> void thenStart(Task<?,? extends Exception> task,
                                                   IAsync<TError2> onErrorOrCancel,
                                                   Function<TError,TError2> errorConverter)

Start the given task when this synchronization point is successfully unblocked, else the error or cancel event are forwarded to the given synchronization point.

thenStart

default void thenStart(String description,
                       byte priority,
                       Runnable task,
                       IAsync<TError> onErrorOrCancel)

Start the given task when this synchronization point is successfully unblocked, else the error or cancel event are forwarded to the given synchronization point.

thenDoOrStart

default boolean thenDoOrStart(Runnable runnable,
                              String taskDescription,
                              byte taskPriority)

Call runnable immediately (in current thread) if done, or start a CPU task on done.

thenDoOrStart

default boolean thenDoOrStart(Runnable runnable,
                              String taskDescription,
                              byte taskPriority,
                              IAsync<TError> onErrorOrCancel)

Call runnable immediately (in current thread) if done, or start a CPU task on done.

thenDoOrStart

default <TError2 extends Exception> boolean thenDoOrStart(Runnable runnable,
                                                          String taskDescription,
                                                          byte taskPriority,
                                                          IAsync<TError2> onErrorOrCancel,
                                                          Function<TError,TError2> errorConverter)

Call runnable immediately (in current thread) if done, or start a CPU task on done.

toAsyncSupplier

default AsyncSupplier<Void,TError> toAsyncSupplier()

Convert this synchronization point into an AsyncWork with Void result.

getAllListeners

Collection<?> getAllListeners()

Return a collection with all listeners, only for debugging purposes.

logListenerError

default void logListenerError(Logger log,
                              Object listener,
                              Throwable error)

Log an error thrown by a listener.