Package org.kiwiproject.concurrent

Class Async

java.lang.Object

org.kiwiproject.concurrent.Async

public final class Async
extends Object

Static utilities that work with CompletableFuture and can make testing easier by permitting selective (e.g., in unit tests) forcing of synchronous behavior for things that would normally execute asynchronously. This applies only to some methods, so read the method's documentation before assuming.

Use the xxxAsync methods when you need to control concurrent behavior and make things deterministic during unit tests (e.g., blocking on futures). Note this does actually change the true behavior of the code under test, since methods will execute synchronously, so use them with care, caution, and understanding.

In tests, you can call the setUnitTestAsyncMode(Mode) method with Async.Mode.DISABLED to force synchronous behavior when calling Async methods. This may be desirable in certain situations to make testing asynchronous code easier. Note that this is a global change, such that all calls to Async methods will then behave as synchronous calls and block until the operation is complete. So, when using this capability in tests, you need to be careful to reset the behavior after tests complete. This may also cause problems if tests are executed in parallel, and some tests use this feature, but some do not.

The kiwi-test library provides a JUnit extension, AsyncModeDisablingExtension, that disables asynchronous behavior in Async before each test, then re-enables it after each test.

Alternatively, you can use AsyncHelper, which will let you control asynchronous behavior in each instance or to use a mock instance in tests. Either of these avoids problems with multiple threads or running tests in parallel.

See Also:

• AsyncHelper

Implementation Note:

the "asyncMode" flag is a STATIC variable and should only ever be changed during testing using the setUnitTestAsyncMode(Mode) method. Generally, you should set this before tests and reset after they have run. Note also this almost certainly will cause unexpected behavior if tests are run in parallel.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	Async.Mode	The Async.Mode.ENABLED mode enables asynchronous behavior, which is the default behavior.

Method Summary

Modifier and Type	Method	Description
static CompletableFuture<Void>	doAsync(Runnable func)	Execute the given Runnable asynchronously.
static CompletableFuture<Void>	doAsync(Runnable func, Executor executor)	Execute the given Runnable asynchronously using the given Executor.
static <T> CompletableFuture<T>	doAsync(Supplier<T> supplier)	Execute the given Supplier asynchronously to return a result, using the common fork join pool as the executor.
static <T> CompletableFuture<T>	doAsync(Supplier<T> supplier, Executor executor)	Execute the given Supplier asynchronously to return a result, using the common fork join pool as the executor.
static CompletableFuture<Void>	runAsync(Runnable func)	Execute the given Runnable asynchronously.
static CompletableFuture<Void>	runAsync(Runnable func, Executor executor)	Execute the given Runnable asynchronously using the given Executor.
static void	setUnitTestAsyncMode(Async.Mode mode)	Use for testing purposes to force synchronous behavior.
static <T> CompletableFuture<T>	supplyAsync(Supplier<T> supplier)	Execute the given Supplier asynchronously to return a result, using the common fork join pool as the executor.
static <T> CompletableFuture<T>	supplyAsync(Supplier<T> supplier, Executor executor)	Execute the given Supplier asynchronously to return a result, using the common fork join pool as the executor.
static <T> void	waitFor(CompletableFuture<T> future, long timeout, TimeUnit unit)	Helper method that waits for a CompletableFuture up to a specified timeout.
static <T> void	waitForAll(Collection<CompletableFuture<T>> futures, long timeout, TimeUnit unit)	Helper method that waits for a collection of CompletableFuture of type T up to a specified timeout.
static void	waitForAllIgnoringType(Collection<CompletableFuture> futures, long timeout, TimeUnit unit)	Helper method that waits for a collection of CompletableFuture with no explicit type up to a specified timeout.
static <T> CompletableFuture<T>	withMaxTimeout(CompletableFuture<T> future, long timeout, TimeUnit unit)	Wraps a CompletableFuture with a timeout so that it can proceed asynchronously, but still have a maximum duration.
static <T> CompletableFuture<T>	withMaxTimeout(CompletableFuture<T> future, long timeout, TimeUnit unit, ExecutorService executor)	Wraps a CompletableFuture with a timeout so that it can proceed asynchronously, but still have a maximum duration.

Methods inherited from class java.lang.Object

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

Method Details

setUnitTestAsyncMode

public static void setUnitTestAsyncMode(Async.Mode mode)

Use for testing purposes to force synchronous behavior.

Parameters:

mode - enable or disable asynchronous behavior

runAsync

public static CompletableFuture<Void> runAsync(Runnable func)

Execute the given Runnable asynchronously. This uses the common fork join pool as the executor.

This is an alias method for doAsync(Runnable) to provide a way to avoid ambiguity in certain situations.

Parameters:

func - the code to run asynchronously

Returns:

a CompletableFuture with no result

See Also:

• ForkJoinPool.commonPool()
• runAsync(Runnable, Executor)

runAsync

public static CompletableFuture<Void> runAsync(Runnable func,
 Executor executor)

Execute the given Runnable asynchronously using the given Executor.

Essentially, wraps CompletableFuture.runAsync(Runnable, Executor) but allowing synchronous behavior if mode is Async.Mode.DISABLED.

This is an alias method for doAsync(Runnable, Executor) to provide a way to avoid ambiguity in certain situations.

Parameters:

func - the code to run asynchronously

executor - the Executor to use

Returns:

a CompletableFuture with no result

See Also:

• CompletableFuture.runAsync(Runnable, Executor)

doAsync

public static CompletableFuture<Void> doAsync(Runnable func)

Execute the given Runnable asynchronously. This uses the common fork join pool as the executor.

Parameters:

func - the code to run asynchronously

Returns:

a CompletableFuture with no result

See Also:

• ForkJoinPool.commonPool()
• doAsync(Runnable, Executor)

doAsync

public static CompletableFuture<Void> doAsync(Runnable func,
 Executor executor)

Execute the given Runnable asynchronously using the given Executor.

Essentially, wraps CompletableFuture.runAsync(Runnable, Executor) but allowing synchronous behavior if mode is Async.Mode.DISABLED.

Parameters:

func - the code to run asynchronously

executor - the Executor to use

Returns:

a CompletableFuture with no result

See Also:

• CompletableFuture.runAsync(Runnable, Executor)

supplyAsync

public static <T> CompletableFuture<T> supplyAsync(Supplier<T> supplier)

Execute the given Supplier asynchronously to return a result, using the common fork join pool as the executor.

This is an alias method for doAsync(Supplier) to provide a way to avoid ambiguity in certain situations.

Type Parameters:

T - the type of object being supplied

Parameters:

supplier - the code to run asynchronously

Returns:

the result returned by the supplier

See Also:

• ForkJoinPool.commonPool()
• doAsync(Supplier, Executor)

supplyAsync

public static <T> CompletableFuture<T> supplyAsync(Supplier<T> supplier,
 Executor executor)

Execute the given Supplier asynchronously to return a result, using the common fork join pool as the executor.

Essentially, wraps CompletableFuture.supplyAsync(Supplier, Executor) but allowing synchronous behavior if mode is Async.Mode.DISABLED.

This is an alias method for doAsync(Supplier, Executor) to provide a way to avoid ambiguity in certain situations.

Type Parameters:

T - the type of object being supplied

Parameters:

supplier - the code to run asynchronously

executor - the Executor to use

Returns:

the result returned by the supplier

See Also:

• ForkJoinPool.commonPool()
• CompletableFuture.supplyAsync(Supplier, Executor)

doAsync

public static <T> CompletableFuture<T> doAsync(Supplier<T> supplier)

Execute the given Supplier asynchronously to return a result, using the common fork join pool as the executor.

Type Parameters:

T - the type of object being supplied

Parameters:

supplier - the code to run asynchronously

Returns:

the result returned by the supplier

See Also:

• ForkJoinPool.commonPool()
• doAsync(Supplier, Executor)

doAsync

public static <T> CompletableFuture<T> doAsync(Supplier<T> supplier,
 Executor executor)

Execute the given Supplier asynchronously to return a result, using the common fork join pool as the executor.

Essentially, wraps CompletableFuture.supplyAsync(Supplier, Executor) but allowing synchronous behavior if mode is Async.Mode.DISABLED.

Type Parameters:

T - the type of object being supplied

Parameters:

supplier - the code to run asynchronously

executor - the Executor to use

Returns:

the result returned by the supplier

See Also:

• ForkJoinPool.commonPool()
• CompletableFuture.supplyAsync(Supplier, Executor)

waitFor

public static <T> void waitFor(CompletableFuture<T> future,
 long timeout,
 TimeUnit unit)

Helper method that waits for a CompletableFuture up to a specified timeout.

Note that Async.Mode has no effect on this method.

Type Parameters:

T - the result returned by the future

Parameters:

future - the CompletableFuture to wait for

timeout - the value of the timeout in the given unit

unit - the time unit to use

Throws:

AsyncException - if any error occurs during asynchronous code execution

waitForAll

public static <T> void waitForAll(Collection<CompletableFuture<T>> futures,
 long timeout,
 TimeUnit unit)

Helper method that waits for a collection of CompletableFuture of type T up to a specified timeout.

Note that Async.Mode has no effect on this method.

Type Parameters:

T - the result returned by the futures

Parameters:

futures - the CompletableFuture instances to wait for

timeout - the value of the timeout in the given unit

unit - the time unit to use

waitForAllIgnoringType

public static void waitForAllIgnoringType(Collection<CompletableFuture> futures,
 long timeout,
 TimeUnit unit)

Helper method that waits for a collection of CompletableFuture with no explicit type up to a specified timeout.

Note that Async.Mode has no effect on this method.

Parameters:

futures - the CompletableFuture instances to wait for

timeout - the value of the timeout in the given unit

unit - the time unit to use

Throws:

AsyncException - if any error occurs during asynchronous code execution

Implementation Note:

Suppressed the IntelliJ and Sonar warnings about raw types

withMaxTimeout

public static <T> CompletableFuture<T> withMaxTimeout(CompletableFuture<T> future,
 long timeout,
 TimeUnit unit)

Wraps a CompletableFuture with a timeout so that it can proceed asynchronously, but still have a maximum duration. Uses the common fork join pool as the ExecutorService.

Note that Async.Mode has no effect on this method.

Type Parameters:

T - the result returned by the future

Parameters:

future - the CompletableFuture for which to apply the timeout

timeout - the value of the timeout in the given unit

unit - the time unit to use

Returns:

the original CompletableFuture wrapped by a new one that applies the given timeout

Throws:

AsyncException - if any error occurs during asynchronous code execution, including timeout

See Also:

• withMaxTimeout(CompletableFuture, long, TimeUnit, ExecutorService)

withMaxTimeout

public static <T> CompletableFuture<T> withMaxTimeout(CompletableFuture<T> future,
 long timeout,
 TimeUnit unit,
 ExecutorService executor)

Wraps a CompletableFuture with a timeout so that it can proceed asynchronously, but still have a maximum duration. Uses the given ExecutorService.

Note that Async.Mode has no effect on this method.

Type Parameters:

T - the result returned by the future

Parameters:

future - the CompletableFuture for which to apply the timeout

timeout - the value of the timeout in the given unit

unit - the time unit to use

executor - the ExecutorService to use

Returns:

the original CompletableFuture wrapped by a new one that applies the given timeout

Throws:

AsyncException - if any error occurs during asynchronous code execution, including timeout

See Also:

• CompletableFuture.supplyAsync(Supplier, Executor)