sirius.kernel.async

Class Tasks

java.lang.Object

sirius.kernel.async.Tasks

All Implemented Interfaces:

Priorized, Killable, Startable, Stoppable

@ParametersAreNonnullByDefault
public class Tasks
extends Object
implements Startable, Stoppable, Killable

Static helper for managing and scheduling asynchronous background tasks.

Provides various helper methods to execute tasks in another thread and to provide interaction via instances of Promise.

Scheduling tasks via executor(String) or defaultExecutor() provides externally configured thread-pools (via async.executor) as well as auto transfer of the current CallContext to the called thread.

Additionally helper-methods for creating and aggregating instances Promise are provided, which are the main interaction model when dealing with async and non-blocking execution.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT Contains the name of the default executor.
protected Map<String,AsyncExecutor>	executors
static int	LIFECYCLE_PRIORITY Contains the priority of this lifecycle.
protected static Log	LOG

Fields inherited from interface sirius.kernel.di.std.Priorized

DEFAULT_PRIORITY

Constructor Summary

Constructors

Constructor and Description
Tasks()

Method Summary

Modifier and Type	Method and Description
void	awaitTermination() Called after Stoppable.stopped() has been called to wait until all tasks are fully finished.
ExecutionBuilder	defaultExecutor() Returns the default executor.
protected void	execute(sirius.kernel.async.ExecutionBuilder.TaskWrapper wrapper)
ExecutionBuilder	executor(String category) Returns the executor for the given category.
ExecutorService	executorService(String category) Exposes the raw executor service for the given category.
<V> Promise<V>	fork(String category, Supplier<V> computation) Forks the given computation and returns a Promise for the computed value.
Collection<AsyncExecutor>	getExecutors() Returns a list of all known executors.
int	getPriority() Returns the priority of this element.
List<Tuple<String,LocalDateTime>>	getScheduledTasks() Returns a list containing the name and estimated execution time of all scheduled tasks which are waiting for their execution.
boolean	isRunning() Determines if the application is still running.
static <V> Promise<List<V>>	sequence(List<Promise<V>> list) Turns a list of promises into a promise for a list of values.
void	started() Invoked when the framework starts up.
void	stopped() Invoked when the framework shuts down.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT

public static final String DEFAULT

Contains the name of the default executor.

See Also:

Constant Field Values

LIFECYCLE_PRIORITY

public static final int LIFECYCLE_PRIORITY

Contains the priority of this lifecycle.

See Also:

Constant Field Values

LOG

protected static final Log LOG

executors

protected final Map<String,AsyncExecutor> executors

Constructor Detail

Tasks

public Tasks()

Method Detail

executor

@Nonnull
public ExecutionBuilder executor(String category)

Returns the executor for the given category.

The configuration for this executor is taken from async.executor.[category]. If no config is found, the default values are used.

Parameters:

category - the category of the task to be executed, which implies the executor to use.

Returns:

the execution builder which submits tasks to the appropriate executor.

defaultExecutor

public ExecutionBuilder defaultExecutor()

Returns the default executor.

Returns:

the execution builder which submits tasks to the default executor.

executorService

@Nonnull
public ExecutorService executorService(String category)

Exposes the raw executor service for the given category.

This shouldn't be used for custom task scheduling (use executor(String) instead) but rather for other frameworks which need an executor service. Using this approach, all thread pools of an application are managed and visible via central facility.

Parameters:

category - the category which is used to specify the capacity of the executor

Returns:

the executor service for the given category

execute

protected void execute(sirius.kernel.async.ExecutionBuilder.TaskWrapper wrapper)

fork

public <V> Promise<V> fork(String category,
                           Supplier<V> computation)

Forks the given computation and returns a Promise for the computed value.

Forks the computation, which means that the current CallContext is transferred to the new thread, and returns the result of the computation as promise.

If the executor for the given category is saturated (all threads are active and the queue is full) this will drop the computation and the promise will be sent a RejectedExecutionException.

Type Parameters:

V - the type of the resulting value

Parameters:

category - the category which implies which executor to use.

computation - the computation which eventually yields the resulting value

Returns:

a promise which will either be eventually supplied with the result of the computation or with an error

sequence

public static <V> Promise<List<V>> sequence(List<Promise<V>> list)

Turns a list of promises into a promise for a list of values.

Note that all values need to have the same type.

If only the completion of all promises matters in contrast to their actual result, a Barrier can also be used. This permits to wait for promises of different types.

Type Parameters:

V - the type of each promise.

Parameters:

list - the list of promises to convert.

Returns:

the promise which will complete if all promises completed or if at least on failed.

getExecutors

public Collection<AsyncExecutor> getExecutors()

Returns a list of all known executors.

Returns:

a collection of all executors which have been used by the system.

isRunning

public boolean isRunning()

Determines if the application is still running.

Can be used for long loops in async tasks to determine if a computation should be interrupted.

Returns:

true if the system is running, false if a shutdown is in progress

getScheduledTasks

public List<Tuple<String,LocalDateTime>> getScheduledTasks()

Returns a list containing the name and estimated execution time of all scheduled tasks which are waiting for their execution.

A scheduled task in this case is one which has ExecutionBuilder.minInterval(Object, Duration) or ExecutionBuilder.frequency(Object, double) set.

Returns:

a list of all scheduled tasks

started

public void started()

Description copied from interface: Startable

Invoked when the framework starts up.

Specified by:

started in interface Startable

stopped

public void stopped()

Description copied from interface: Stoppable

Invoked when the framework shuts down.

This method must not block (and wait for internals to stop). This can be done in Killable.awaitTermination().

Specified by:

stopped in interface Stoppable

awaitTermination

public void awaitTermination()

Description copied from interface: Killable

Called after Stoppable.stopped() has been called to wait until all tasks are fully finished.

This method may block for a certain amount of time to permit the subsystem to shut down properly. However, it should not block infinitely...

Specified by:

awaitTermination in interface Killable

getPriority

public int getPriority()

Description copied from interface: Priorized

Returns the priority of this element.

Specified by:

getPriority in interface Priorized

Specified by:

getPriority in interface Killable

Specified by:

getPriority in interface Startable

Specified by:

getPriority in interface Stoppable

Returns:

the priority - lower is better (comes first)