Package uk.ac.diamond.daq.concurrent

Class Async

java.lang.Object

uk.ac.diamond.daq.concurrent.Async

public final class Async
extends Object

Utility methods used to run short-lived tasks asynchronously.

Tasks are run in their own thread. Existing idle threads will be reused if possible to minimise overhead of creating new threads.

This is intended to replace the use of

 new Thread(new Runnable() {
     public void run() {
         // do stuff
     }
 }).start();
 

with

 Async.execute(() -> {
     // do stuff
 });
 

Repeating tasks can also be submitted in a similar way to using ScheduledExecutorServices. For most uses, a thread running to execute something every second or so is idle for the majority of the time. This allows fewer threads to be running and to reduce the idle time.

Since:

9.8

See Also:

• ExecutorService
• ScheduledExecutorService
• Future

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Async.ListeningFuture<T>	A future that wraps a ListeningFuture and accepts success/failure callbacks.
static class	Async.ListeningScheduledFuture<T>	A future that wraps a ListeningScheduledFuture and accepts success/failure callbacks.

Method Summary

Modifier and Type	Method	Description
static Async.ListeningFuture<?>	call(Callable<?> target)	Submit a callable object to be run asynchronously.
static void	execute(Runnable target)	Run a Runnable in its own thread.
static void	execute(Runnable target, String nameFormat, Object... args)	Run a Runnable in its own named thread.
static Future<Collection<Future<Object>>>	executeAll(Runnable... tasks)	Submit a collection of Runnables to be executed concurrently.
static Future<Collection<Future<Object>>>	executeAll(Collection<Runnable> tasks)	Submit a collection of Runnables to be executed concurrently.
static Async.ListeningScheduledFuture<?>	schedule(Runnable target, long delay, TimeUnit unit)	Schedule a task to run after a given delay.
static Async.ListeningScheduledFuture<?>	schedule(Runnable target, long delay, TimeUnit unit, String nameFormat, Object... args)	Schedule a task to run after a given delay.
static <T> Async.ListeningScheduledFuture<T>	schedule(Callable<T> target, long delay, TimeUnit unit)	Schedule a task to run after a given delay.
static <T> Async.ListeningScheduledFuture<T>	schedule(Callable<T> target, long delay, TimeUnit unit, String nameFormat, Object... args)	Schedule a task to run after a given delay.
static ScheduledFuture<?>	scheduleAtFixedRate(Runnable target, long delay, long period, TimeUnit unit)	Schedule a task to be run repeatedly at a fixed rate after an initial delay.
static Async.ListeningScheduledFuture<?>	scheduleAtFixedRate(Runnable target, long delay, long period, TimeUnit unit, String nameFormat, Object... args)	Schedule a task to be run repeatedly at a fixed rate after an initial delay.
static ScheduledFuture<?>	scheduleWithFixedDelay(Runnable target, long delay, long period, TimeUnit unit)	Schedule a task to be run repeatedly with a fixed delay between executions.
static Async.ListeningScheduledFuture<?>	scheduleWithFixedDelay(Runnable target, long delay, long period, TimeUnit unit, String nameFormat, Object... args)	Schedule a task to be run repeatedly with a fixed delay between executions.
static Async.ListeningFuture<?>	submit(Runnable target)	Submit a task to be run in its own thread.
static Async.ListeningFuture<?>	submit(Runnable target, String nameFormat, Object... args)	Submit a task to be run in its own thread.
static <T> Async.ListeningFuture<T>	submit(Callable<T> target)	Submit a task to be run in its own thread.
static <T> Async.ListeningFuture<T>	submit(Callable<T> target, String nameFormat, Object... args)	Submit a task to be run in its own named thread.
static <T> Future<Collection<Future<T>>>	submitAll(Collection<Callable<T>> tasks)	Submit a list of callables to be executed concurrently.
static <T> Future<Collection<Future<T>>>	submitAll(Callable<T>... tasks)	Submit a list of callables to be executed concurrently.

Methods inherited from class java.lang.Object

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

Method Details

execute

public static void execute(Runnable target)

Run a Runnable in its own thread.

Parameters:

target - The task to be run

Since:

9.8

See Also:

• Executor.execute(Runnable)

execute

public static void execute(Runnable target,
 String nameFormat,
 Object... args)

Run a Runnable in its own named thread. The name is created using String.format(java.lang.String, java.lang.Object...) with the given nameFormat and args

Parameters:

target - The task to be run

nameFormat - The name of the thread to run this task

args - Objects to format the name with

Since:

9.8

See Also:

• Executor.execute(Runnable)

submit

public static <T> Async.ListeningFuture<T> submit(Callable<T> target)

Submit a task to be run in its own thread. Returns a Future giving access to the completion or error state of the task and allowing tasks to be cancelled.

The Future also gives access to the return value of the target.

The returned Future can have callbacks added to be run on success or failure of the callable. See onSuccess and onFailure.

Type Parameters:

T - the return type of the task to be run

Parameters:

target - The task to be run

Returns:

A Future

Since:

9.8

See Also:

• ExecutorService.submit(Callable)
• Future

submit

public static <T> Async.ListeningFuture<T> submit(Callable<T> target,
 String nameFormat,
 Object... args)

Submit a task to be run in its own named thread. Returns a Future giving access to the completion or error state of the task and allowing tasks to be cancelled.

The Future also gives access to the return value of the Callable.

This method differs from submit(Callable) in that it renames the thread before running the task. The name is created using String.format(java.lang.String, java.lang.Object...) with the given nameFormat and args.

The returned Future can have callbacks added to be run on success or failure of the callable. See onSuccess and onFailure.

Type Parameters:

T - the return type of the task to be run

Parameters:

target - The task to be run

nameFormat - For the thread used to run this task

args - Objects to format the name with

Returns:

A Future

Since:

9.8

See Also:

• ExecutorService.submit(Callable)
• Future

submit

public static Async.ListeningFuture<?> submit(Runnable target)

Submit a task to be run in its own thread. Returns a Future giving access to the completion or error state of the task and allowing tasks to be cancelled.

The Future's get method will return null on successful completion.

The returned Future can have callbacks added to be run on success or failure of the runnable. See onSuccess and onFailure.

Parameters:

target - The task to be run

Returns:

Future giving access to the state of the running task

Since:

9.8

See Also:

• ExecutorService.submit(Runnable)
• Future

submit

public static Async.ListeningFuture<?> submit(Runnable target,
 String nameFormat,
 Object... args)

Submit a task to be run in its own thread. Returns a Future giving access to the completion or error state of the task and allowing tasks to be cancelled.

The Future's get method will return null on successful completion

This differs from submit(Runnable) in that it renames the thread before running the task. The name is created using String.format(java.lang.String, java.lang.Object...) with the given nameFormat and args.

The returned Future can have callbacks added to be run on success or failure of the runnable. See onSuccess and onFailure.

Parameters:

target - The task to be run

nameFormat - For the thread used to run this task

args - Objects to format the name with

Returns:

Future giving access to the state of the running task

Since:

9.8

See Also:

• ExecutorService.submit(Runnable)
• Future

submitAll

public static <T> Future<Collection<Future<T>>> submitAll(Collection<Callable<T>> tasks)

Submit a list of callables to be executed concurrently. Returns a future whose get method returns a list of Futures representing the individual tasks. The future will only complete when all of the individual tasks are complete (whether with success or failure or cancellation).

Type Parameters:

T - The return type of the given callables

Parameters:

tasks - a collection of callables to be executed concurrently.

Returns:

a Future representing the state of all the tasks

See Also:

• ExecutorService.invokeAll(Collection)

submitAll

@SafeVarargs
public static <T> Future<Collection<Future<T>>> submitAll(Callable<T>... tasks)

Submit a list of callables to be executed concurrently. Returns a future whose get method returns a list of Futures representing the individual tasks. The future will only complete when all of the individual tasks are complete (whether with success or failure or cancellation).

Type Parameters:

T - The return type of the given callables

Parameters:

tasks - a collection of callables to be executed concurrently.

Returns:

a Future representing the state of all the tasks

See Also:

• ExecutorService.invokeAll(Collection)

executeAll

public static Future<Collection<Future<Object>>> executeAll(Collection<Runnable> tasks)

Submit a collection of Runnables to be executed concurrently. Returns a Future whose get method returns a list of Futures when all tasks are complete (whether successful or not). For successful runnables, the get method of the returned Future will return null.

The future.get method of unsuccessful tasks will throw an ExecutionException.

Parameters:

tasks - The collection of tasks to execute concurrently

Returns:

Future holding list of futures of the individual tasks

See Also:

• submitAll(Collection)

executeAll

public static Future<Collection<Future<Object>>> executeAll(Runnable... tasks)

Submit a collection of Runnables to be executed concurrently. Returns a Future whose get method returns a list of Futures when all tasks are complete (whether successful or not). For successful runnables, the get method of the returned Future will return null.

The future.get method of unsuccessful tasks will throw an ExecutionException.

Parameters:

tasks - The collection of tasks to execute concurrently

Returns:

Future holding list of futures of the individual tasks

See Also:

• submitAll(Collection)

scheduleAtFixedRate

public static ScheduledFuture<?> scheduleAtFixedRate(Runnable target,
 long delay,
 long period,
 TimeUnit unit)

Schedule a task to be run repeatedly at a fixed rate after an initial delay.

This differs from scheduleWithFixedDelay(java.lang.Runnable, long, long, java.util.concurrent.TimeUnit) in that the time between executions can vary if the duration of the task is variable.

Parameters:

target - The task to run

delay - The time before the initial execution

period - The period between successive executions

unit - Time unit of delay and period

Returns:

ScheduledFuture giving caller ability to check status and cancel task

Since:

9.8

See Also:

• ScheduledFuture
• ScheduledExecutorService.scheduleAtFixedRate(Runnable, long, long, TimeUnit)

scheduleAtFixedRate

public static Async.ListeningScheduledFuture<?> scheduleAtFixedRate(Runnable target,
 long delay,
 long period,
 TimeUnit unit,
 String nameFormat,
 Object... args)

Schedule a task to be run repeatedly at a fixed rate after an initial delay.

This differs from scheduleWithFixedDelay(java.lang.Runnable, long, long, java.util.concurrent.TimeUnit) in that the time between executions can vary if the duration of the task is variable.

This differs from scheduleAtFixedRate(Runnable, long, long, TimeUnit) in that it renames the thread before running the task. The name is created using String.format(java.lang.String, java.lang.Object...) with the given nameFormat and args.

Parameters:

target - The task to run

delay - The time before the initial execution

period - The period between successive executions

unit - Time unit of delay and period

nameFormat - For the thread used to run this task

args - Objects to format the name with

Returns:

Future giving caller ability to check status and cancel task

Since:

9.8

See Also:

• Future
• ScheduledExecutorService.scheduleAtFixedRate(Runnable, long, long, TimeUnit)

scheduleWithFixedDelay

public static ScheduledFuture<?> scheduleWithFixedDelay(Runnable target,
 long delay,
 long period,
 TimeUnit unit)

Schedule a task to be run repeatedly with a fixed delay between executions. The first execution can be delayed by a different amount of time.

This differs from scheduleAtFixedRate(java.lang.Runnable, long, long, java.util.concurrent.TimeUnit) in that the period can vary if the duration of the task is variable;

Parameters:

target - The task to run

delay - The time before the initial execution

period - The time between successive executions

unit - Time unit of delay and period

Returns:

ScheduledFuture giving caller ability to check status and cancel task

Since:

9.8

See Also:

• ScheduledFuture
• ScheduledExecutorService.scheduleWithFixedDelay(Runnable, long, long, TimeUnit)

scheduleWithFixedDelay

public static Async.ListeningScheduledFuture<?> scheduleWithFixedDelay(Runnable target,
 long delay,
 long period,
 TimeUnit unit,
 String nameFormat,
 Object... args)

Schedule a task to be run repeatedly with a fixed delay between executions. The first execution can be delayed by a different amount of time.

This differs from scheduleAtFixedRate(java.lang.Runnable, long, long, java.util.concurrent.TimeUnit) in that the period can vary if the duration of the task is variable.

This differs from scheduleWithFixedDelay(Runnable, long, long, TimeUnit) in that it renames the thread before running the task. The name is created using String.format(java.lang.String, java.lang.Object...) with the given nameFormat and args.

Parameters:

target - The task to run

delay - The time before the initial execution

period - The time between successive executions

unit - Time unit of delay and period

nameFormat - For the thread used to run this task

args - Objects to format the name with

Returns:

ScheduledFuture giving caller ability to check status and cancel task

Since:

9.8

See Also:

• ScheduledFuture
• ScheduledExecutorService.scheduleWithFixedDelay(Runnable, long, long, TimeUnit)

schedule

public static Async.ListeningScheduledFuture<?> schedule(Runnable target,
 long delay,
 TimeUnit unit)

Schedule a task to run after a given delay. The remaining time and status of the task can be checked by the caller using the returned future. Future.get() will return null after the task is complete.

The returned Future can have callbacks added to be run on success or failure of the runnable. See onSuccess and onFailure.

Parameters:

target - The task to run

delay - The time to wait before running

unit - The units of the given delay

Returns:

A ScheduledFuture giving access to status of task

Since:

9.8

See Also:

• ScheduledFuture
• ScheduledExecutorService.schedule(Runnable, long, TimeUnit)

schedule

public static Async.ListeningScheduledFuture<?> schedule(Runnable target,
 long delay,
 TimeUnit unit,
 String nameFormat,
 Object... args)

Schedule a task to run after a given delay. The remaining time and status of the task can be checked by the caller using the returned future. Future.get() will return null after the task is complete.

This differs from schedule(Runnable, long, TimeUnit) in that it renames the thread before running the task. The name is created using String.format(java.lang.String, java.lang.Object...) with the given nameFormat and args.

The returned Future can have callbacks added to be run on success or failure of the runnable. See onSuccess and onFailure.

Parameters:

target - The task to run

delay - The time to wait before running

unit - The units of the given delay

nameFormat - For the thread used to run this task

args - Objects to format the name with

Returns:

A ScheduledFuture giving access to status of task

Since:

9.8

See Also:

• ScheduledFuture
• ScheduledExecutorService.schedule(Runnable, long, TimeUnit)

schedule

public static <T> Async.ListeningScheduledFuture<T> schedule(Callable<T> target,
 long delay,
 TimeUnit unit)

Schedule a task to run after a given delay. The remaining time and status of the task can be checked by the caller using the returned future. Future.get() will return the result of the task after completion.

The returned Future can have callbacks added to be run on success or failure of the callable. See onSuccess and onFailure.

Type Parameters:

T - The return type of the given task

Parameters:

target - The task to run

delay - The time to wait before running

unit - The units of the given delay

Returns:

A ScheduledFuture giving access to status of task

See Also:

• ScheduledFuture
• ScheduledExecutorService.schedule(Callable, long, TimeUnit)

schedule

public static <T> Async.ListeningScheduledFuture<T> schedule(Callable<T> target,
 long delay,
 TimeUnit unit,
 String nameFormat,
 Object... args)

Schedule a task to run after a given delay. The remaining time and status of the task can be checked by the caller using the returned future. Future.get() will return the result of the task after completion.

This differs from schedule(Callable, long, TimeUnit) in that it renames the thread before running the task. The name is created using String.format(java.lang.String, java.lang.Object...) with the given nameFormat and args.

The returned Future can have callbacks added to be run on success or failure of the callable. See onSuccess and onFailure.

Type Parameters:

T - The return type of the given task

Parameters:

target - The task to run

delay - The time to wait before running

unit - The units of the given delay

nameFormat - For the thread used to run this task

args - Objects to format the name with

Returns:

A ScheduledFuture giving access to status of task

See Also:

• ScheduledFuture
• ScheduledExecutorService.schedule(Callable, long, TimeUnit)

call

public static Async.ListeningFuture<?> call(Callable<?> target)

Submit a callable object to be run asynchronously. This method is a duplicate of submit(Callable) and only exists to work around a Jython bug where incorrect type resolution is used (Callable python objects are used as Runnables instead so return values are lost).

In most cases, Jython functions and methods are callable. If a method needs parameters passed to it, a lambda can be used. eg

 >>> def add(a, b):
 ...     sleep(10)
 ...     return a + b
 ...
 >>> future = Async.call(lambda: add(1, 2))
 >>> future.get() # waits (just under) 10 seconds before returning
 3
 

This can also be used to execute things that can't be cast to Callable directly (eg classes with __call__ method). The returned Future can be used as normal to cancel or get the return value.

The returned Future can have callbacks added to be run on success or failure of the callable. See onSuccess and onFailure.

Parameters:

target - should be callable

Returns:

Future giving access to PyObject returned by callable. PyNone if void function

Since:

9.8

See Also:

• Future