Package org.kiwiproject.concurrent

Class AsyncHelper

java.lang.Object

org.kiwiproject.concurrent.AsyncHelper

public class AsyncHelper
extends Object

This helper class wraps the static utility functions in Async. You need to create an instance of this class to use it. The main reason to use this instead of Async directly is to have more control over disabling asynchronous behavior, which should usually only be done in test code.

By default, all operations are asynchronous like Async. You can call setUnitTestAsyncMode(Async.Mode) with Async.Mode.DISABLED to force synchronous behavior when calling AsyncHelper methods. Also like Async, some methods ignore Async.Mode, and is noted in their Javadocs.

Using an instance of this class instead of Async directly will make it much easier to test asynchronous code. As mentioned above, you can set the Async.Mode to Async.Mode.DISABLED before each test to execute the code synchronously in tests. Unlike using Async directly in tests, there are no problems using AsyncHelper with multiple threads or parallel test execution. You can also choose to use a mock AsyncHelper in tests and specify the desired behavior, which means you are bypassing the asynchronous calls entirely. This may be appropriate in some situations, for example, when the asynchronous behavior has been tested in other tests, and you want to simplify test code. As always, the choice depends on the situation.

See Also:

• Async

Constructor Summary

Constructors

Constructor	Description
AsyncHelper()

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Void>	doAsync(Runnable func)	Execute the given Runnable asynchronously.
CompletableFuture<Void>	doAsync(Runnable func, Executor executor)	Execute the given Runnable asynchronously using the given Executor.
<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.
<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.
CompletableFuture<Void>	runAsync(Runnable func)	Execute the given Runnable asynchronously.
CompletableFuture<Void>	runAsync(Runnable func, Executor executor)	Execute the given Runnable asynchronously using the given Executor.
void	setUnitTestAsyncMode(Async.Mode mode)	Use for testing purposes to force synchronous behavior.
<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.
<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.
<T> void	waitFor(CompletableFuture<T> future, long timeout, TimeUnit unit)	Helper method that waits for a CompletableFuture up to a specified timeout.
<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.
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.
<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.
<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

Constructor Details

AsyncHelper

public AsyncHelper()

Method Details

setUnitTestAsyncMode

public void setUnitTestAsyncMode(Async.Mode mode)

Use for testing purposes to force synchronous behavior.

Parameters:

mode - enable or disable asynchronous behavior

runAsync

public 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 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 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 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 <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 <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 <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 <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 <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 <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 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 <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 <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)