net.lecousin.framework.concurrent.async

Class JoinPoint<TError extends Exception>

java.lang.Object

net.lecousin.framework.concurrent.async.Async<TError>

net.lecousin.framework.concurrent.async.JoinPoint<TError>

Type Parameters:

TError - type of exception it may raise

All Implemented Interfaces:

Future<Void>, Cancellable, IAsync<TError>

public class JoinPoint<TError extends Exception>
extends Async<TError>

A JoinPoint allows to wait for several synchronization points or events, instead of a single one. The methods addToJoin can be first called to add events to wait for. Then, the method start must be called. At the time it is called, if all waited events are already done, or the number of waited events is 0, this JoinPoint is immediately unblocked, else, each time an event is done, we check if this is the last one.
A JoinPoint can be used a single time, as a SynchronizationPoint. In other words, once it is unblocked, it remains unblocked.
Note that, like a SynchronizationPoint, if a JoinPoint is cancelled, or an error is given, the JoinPoint becomes immediately unblocked, whatever there are remaining waited events or not, and whatever it has been started already or not.

Constructor Summary

Constructors

Constructor and Description
JoinPoint() Constructor.

Method Summary

Modifier and Type	Method and Description
void	addToJoin(IAsync<?> sp, Function<Exception,TError> errorConverter) Register the given synchronization point as a waited event for this JoinPoint. The number of waited events is incremented, and a listener is added to the synchronization point and do the following when the synchronization point is unblocked: Cancel this JoinPoint if the synchronization point is cancelled Unblock this JoinPoint with an error if the synchronization point has been unblocked with an error Call the joined method if the synchronization point has been unblocked with success
void	addToJoin(IAsync<? extends TError> sp) Register the given synchronization point as a waited event for this JoinPoint. The number of waited events is incremented, and a listener is added to the synchronization point and do the following when the synchronization point is unblocked: Cancel this JoinPoint if the synchronization point is cancelled Unblock this JoinPoint with an error if the synchronization point has been unblocked with an error Call the joined method if the synchronization point has been unblocked with success
void	addToJoin(int nb) Specify that we are waiting for the given number of additional events.
void	addToJoin(Task<?,? extends TError> task) Register the given task as a waited event for this JoinPoint. Equivalent to addToJoin(task.getSynch())
void	addToJoinDoNotCancel(IAsync<? extends TError> sp) Similar to addToJoin, but in case the synchronization point is cancelled, it is simply consider as done, and do not cancel this JoinPoint.
void	addToJoinNoException(IAsync<?> sp) Register the given synchronization point as a waited event for this JoinPoint. The number of waited events is incremented, and a listener is added to the synchronization point.
static JoinPoint<Exception>	from(Collection<? extends IAsync<?>> synchPoints) Shortcut method to create a JoinPoint waiting for the given synchronization points, the JoinPoint is started by this method.
static JoinPoint<Exception>	from(IAsync<?>... synchPoints) Shortcut method to create a JoinPoint waiting for the given synchronization points, the JoinPoint is started by this method.
static <T extends Exception> JoinPoint<T>	fromSimilarError(IAsync<T>... synchPoints) Shortcut method to create a JoinPoint waiting for the given synchronization points, the JoinPoint is started by this method. If some given synchronization points are null, they are just skipped.
static JoinPoint<Exception>	fromTasks(Collection<? extends Task<?,?>> tasks) Shortcut method to create a JoinPoint waiting for the given tasks, the JoinPoint is started by this method. If any task has error or is cancelled, the join point is immediately unblocked, even other tasks are still pending.
static JoinPoint<Exception>	fromTasks(Task<?,?>... tasks) Shortcut method to create a JoinPoint waiting for the given tasks, the JoinPoint is started by this method. If any task has error or is cancelled, the join point is immediately unblocked, even other tasks are still pending.
static JoinPoint<NoException>	fromTasksNoErrorOrCancel(Collection<? extends Task<?,?>> tasks) Shortcut method to create a JoinPoint waiting for the given tasks, the JoinPoint is started by this method. The JoinPoint is not unblocked until all tasks are done.
int	getToJoin() Return the number of remaining events this JoinPoint is waiting for.
void	joined() Method to be called to signal that an event is done. The number of waited events is decremented, if it becomes 0 this JoinPoint is unblocked with success.
static void	joinOnDoneThenDo(Runnable listener, IAsync<?>... synchPoints) Shortcut method to create a JoinPoint waiting for the given synchronization points, start the JoinPoint, and add the given listener to be called when the JoinPoint is unblocked.
static void	joinThenDo(Runnable listener, IAsync<?>... synchPoints) Shortcut method to create a JoinPoint waiting for the given synchronization points, start the JoinPoint, and add the given listener to be called when the JoinPoint is unblocked.
void	listenTime(long timeout, Runnable callback) Call the given callback if this JoinPoint is still not yet unblocked after the given number of milliseconds.
void	start() Start this JoinPoint, so as soon as the number of waited events becomes zero, this JoinPoint becomes unblocked.
void	timeout(long millis, Runnable callback) Should be used only for debugging purpose, as a JoinPoint is supposed to always become unblocked. This method will wait for the given milliseconds, if at this time the JoinPoint is already unblocked, nothing is done, else we force it to become unblocked, and the given callback is called if any.

Methods inherited from class net.lecousin.framework.concurrent.async.Async

block, blockPauseCondition, cancel, cancel, error, get, get, getAllListeners, getCancelEvent, getError, hasError, isCancelled, isDone, onDone, reset, restart, unblock

Methods inherited from class java.lang.Object

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

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

blockException, blockPause, blockThrow, forwardIfNotSuccessful, isSuccessful, logListenerError, onCancel, onDone, onDone, onDone, onDone, onDone, onDone, onError, onErrorOrCancel, onSuccess, thenDoOrStart, thenDoOrStart, thenDoOrStart, thenStart, thenStart, thenStart, thenStart, thenStart, thenStart, toAsyncSupplier

Constructor Detail

JoinPoint

public JoinPoint()

Constructor.

Method Detail

getToJoin

public int getToJoin()

Return the number of remaining events this JoinPoint is waiting for.

addToJoin

public void addToJoin(int nb)

Specify that we are waiting for the given number of additional events. The method joined will need to be called for every of those events, in order to unblock this JoinPoint.

addToJoin

public void addToJoin(IAsync<? extends TError> sp)

Register the given synchronization point as a waited event for this JoinPoint.
The number of waited events is incremented, and a listener is added to the synchronization point and do the following when the synchronization point is unblocked:

• Cancel this JoinPoint if the synchronization point is cancelled
• Unblock this JoinPoint with an error if the synchronization point has been unblocked with an error
• Call the joined method if the synchronization point has been unblocked with success

addToJoin

public void addToJoin(IAsync<?> sp,
                      Function<Exception,TError> errorConverter)

Register the given synchronization point as a waited event for this JoinPoint.
The number of waited events is incremented, and a listener is added to the synchronization point and do the following when the synchronization point is unblocked:

• Cancel this JoinPoint if the synchronization point is cancelled
• Unblock this JoinPoint with an error if the synchronization point has been unblocked with an error
• Call the joined method if the synchronization point has been unblocked with success

addToJoin

public void addToJoin(Task<?,? extends TError> task)

Register the given task as a waited event for this JoinPoint.
Equivalent to addToJoin(task.getSynch())

addToJoinNoException

public void addToJoinNoException(IAsync<?> sp)

Register the given synchronization point as a waited event for this JoinPoint.
The number of waited events is incremented, and a listener is added to the synchronization point. Once the synchronization point is unblock (whatever it succeed, it has an error or it has been cancelled) the joined method is called.

addToJoinDoNotCancel

public void addToJoinDoNotCancel(IAsync<? extends TError> sp)

Similar to addToJoin, but in case the synchronization point is cancelled, it is simply consider as done, and do not cancel this JoinPoint.

start

public void start()

Start this JoinPoint, so as soon as the number of waited events becomes zero, this JoinPoint becomes unblocked.

joined

public void joined()

Method to be called to signal that an event is done.
The number of waited events is decremented, if it becomes 0 this JoinPoint is unblocked with success.

timeout

public void timeout(long millis,
                    Runnable callback)

Should be used only for debugging purpose, as a JoinPoint is supposed to always become unblocked.
This method will wait for the given milliseconds, if at this time the JoinPoint is already unblocked, nothing is done, else we force it to become unblocked, and the given callback is called if any.

listenTime

public void listenTime(long timeout,
                       Runnable callback)

Call the given callback if this JoinPoint is still not yet unblocked after the given number of milliseconds. This method is similar to the method timeout, except that this JoinPoint is not unblocked when the timeout is reached.

from

public static JoinPoint<Exception> from(IAsync<?>... synchPoints)

Shortcut method to create a JoinPoint waiting for the given synchronization points, the JoinPoint is started by this method.

from

public static JoinPoint<Exception> from(Collection<? extends IAsync<?>> synchPoints)

Shortcut method to create a JoinPoint waiting for the given synchronization points, the JoinPoint is started by this method.

fromSimilarError

@SafeVarargs
public static <T extends Exception> JoinPoint<T> fromSimilarError(IAsync<T>... synchPoints)

Shortcut method to create a JoinPoint waiting for the given synchronization points, the JoinPoint is started by this method. If some given synchronization points are null, they are just skipped.

fromTasks

public static JoinPoint<Exception> fromTasks(Task<?,?>... tasks)

Shortcut method to create a JoinPoint waiting for the given tasks, the JoinPoint is started by this method. If any task has error or is cancelled, the join point is immediately unblocked, even other tasks are still pending.

fromTasks

public static JoinPoint<Exception> fromTasks(Collection<? extends Task<?,?>> tasks)

Shortcut method to create a JoinPoint waiting for the given tasks, the JoinPoint is started by this method. If any task has error or is cancelled, the join point is immediately unblocked, even other tasks are still pending.

fromTasksNoErrorOrCancel

public static JoinPoint<NoException> fromTasksNoErrorOrCancel(Collection<? extends Task<?,?>> tasks)

Shortcut method to create a JoinPoint waiting for the given tasks, the JoinPoint is started by this method. The JoinPoint is not unblocked until all tasks are done. If any has error or is cancel, the error or cancellation reason is not given to the JoinPoint, in contrary of the method fromTasks.

joinThenDo

public static void joinThenDo(Runnable listener,
                              IAsync<?>... synchPoints)

Shortcut method to create a JoinPoint waiting for the given synchronization points, start the JoinPoint, and add the given listener to be called when the JoinPoint is unblocked. If any synchronization point has an error or is cancelled, the JoinPoint is immediately unblocked. If some given synchronization points are null, they are just skipped.

joinOnDoneThenDo

public static void joinOnDoneThenDo(Runnable listener,
                                    IAsync<?>... synchPoints)

Shortcut method to create a JoinPoint waiting for the given synchronization points, start the JoinPoint, and add the given listener to be called when the JoinPoint is unblocked. The JoinPoint is not unblocked until all synchronization points are unblocked. If any has error or is cancel, the error or cancellation reason is not given to the JoinPoint, in contrary of the method listenInline.