Tasks (Sirius Kernel 3.3 API)

java.lang.Object
- sirius.kernel.async.Tasks

All Implemented Interfaces:

Priorized, Lifecycle
```
@ParametersAreNonnullByDefault
public class Tasks
extends Object
implements Lifecycle
```
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()

Constructors
Constructor and Description
`Tasks()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`awaitTermination()` Called after `Lifecycle.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.
`static <V> Promise<V>`	`fail(Throwable ex)` Generates a promise which has immediately failed.
`<V> Promise<V>`	`fork(String category, java.util.function.Supplier<V> computation)` Forks the given computation and returns a `Promise` for the computed value.
`static Future`	`future()` Creates a new future, which is just an untyped `Promise` where the completion is more important than the actual result of the computation.
`Collection<AsyncExecutor>`	`getExecutors()` Returns a list of all known executors.
`String`	`getName()` Returns a short name for this lifecycle.
`int`	`getPriority()` Returns the priority of this element.
`List<Tuple<String,java.time.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<V>`	`promise()` Creates a new promise of the given type.
`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.
`static <V> Promise<V>`	`success(V value)` Generates a promise which is immediately successful.

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
```
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.
  - execute
```
protected void execute(sirius.kernel.async.ExecutionBuilder.TaskWrapper wrapper)
```
  - fork
```
public <V> Promise<V> fork(String category,
                           java.util.function.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
  - promise
```
public static <V> Promise<V> promise()
```
    Creates a new promise of the given type.
    
    Type Parameters:
    
    V - the type of the result which is promised.
    
    Returns:
    
    a new Promise which can be used to represent an asynchronously computed value.
  - future
```
public static Future future()
```
    Creates a new future, which is just an untyped Promise where the completion is more important than the actual result of the computation.
    
    Returns:
    
    a new Future which can be used to wait for a computation without a specific result.
  - success
```
public static <V> Promise<V> success(@Nullable
                                     V value)
```
    Generates a promise which is immediately successful.
    
    Type Parameters:
    
    V - the type of the promise (or its promised value)
    
    Parameters:
    
    value - the value which is used as promised result
    
    Returns:
    
    a promise which is already completed with the given value.
  - fail
```
public static <V> Promise<V> fail(Throwable ex)
```
    Generates a promise which has immediately failed.
    
    Type Parameters:
    
    V - the type of the promise (or its promised value)
    
    Parameters:
    
    ex - the error which is used as failure
    
    Returns:
    
    a promise which is already completed, but failed with the given 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,java.time.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: Lifecycle
    
    Invoked when the framework starts up.
    
    Specified by:
    
    started in interface Lifecycle
  - stopped
```
public void stopped()
```
    Description copied from interface: Lifecycle
    
    Invoked when the framework shuts down.
    This method must not block (and wait for internals to stop). This can be done in Lifecycle.awaitTermination().
    
    Specified by:
    
    stopped in interface Lifecycle
  - awaitTermination
```
public void awaitTermination()
```
    Description copied from interface: Lifecycle
    
    Called after Lifecycle.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 Lifecycle
  - getName
```
public String getName()
```
    Description copied from interface: Lifecycle
    
    Returns a short name for this lifecycle.
    
    Specified by:
    
    getName in interface Lifecycle
    
    Returns:
    
    the name of this component, used for log outputs.
  - 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 Lifecycle
    
    Returns:
    
    the priority - lower is better (comes first)

Class Tasks

Field Summary

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

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT

LIFECYCLE_PRIORITY

LOG

executors

Constructor Detail

Tasks

Method Detail

executor

defaultExecutor

execute

fork

promise

future

success

fail

sequence

getExecutors

isRunning

getScheduledTasks

started

stopped

awaitTermination

getName

getPriority