sirius.kernel.async

Class Barrier

java.lang.Object

sirius.kernel.async.Barrier

@ParametersAreNonnullByDefault
public class Barrier
extends Object

Provides a simple barrier to wait for the completion of a set of tasks represented by Barrier.

A Barrier can be used to block and wait for the completion of a given set of promises. A barrier should only be used once and after a call to await, no further promises should be added. Also await must only be called once.

The general call pattern looks like that:

 
      Barrier b = Barrier.create();
      b.add(somePromise);
      b.add(anotherPromise);

      b.await(1, TimeUnit.MINUTE);
 
 

Always prefer await(long, java.util.concurrent.TimeUnit) and specify a sane timeout since something might always go wrong and a promise might therefore not complete (in time - or not at all) and your program is locked forever.

This barrier can also be used in a non-blocking way, by calling asFuture() after the last call to add(Promise). If possible, the non-block approach should always be preferred.

Constructor Summary

Constructors

Constructor and Description
Barrier()

Method Summary

Modifier and Type	Method and Description
void	add(Promise<?> promise) Adds a promise to the barrier which will be waited for.
Future	asFuture() Generates a new Future which completes if the las added promise completes or if any one of those fails.
void	await() Waits until all previously added promises completed (either successfully or failed).
boolean	await(long time, TimeUnit unit) Waits until all previously added promises completed or the given timeout expires.
static Barrier	create() Creates a new barrier.

Methods inherited from class java.lang.Object

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

Constructor Detail

Barrier

public Barrier()

Method Detail

create

public static Barrier create()

Creates a new barrier.

Returns:

a new empty barrier.

add

public void add(Promise<?> promise)

Adds a promise to the barrier which will be waited for.

Note that one must not call add after calling await.

Parameters:

promise - the promise to wait for

asFuture

public Future asFuture()

Generates a new Future which completes if the las added promise completes or if any one of those fails.

Returns:

a new future which can used to add completion handlers for all added promises.

await

public void await()
           throws InterruptedException

Waits until all previously added promises completed (either successfully or failed).

Note that this method might block for an indefinite amount of time. Consider using await(long, java.util.concurrent.TimeUnit) and specify a sane timeout

Throws:

InterruptedException - if the thread was interrupted while waiting for completion.

await

public boolean await(long time,
                     TimeUnit unit)

Waits until all previously added promises completed or the given timeout expires.

Parameters:

time - the number of time intervals to wait for completion

unit - the unit of time intervals to wait for completion

Returns:

true if all promises completed within the given timout, false otherwise.