ParallelRunner

package saker.build.thirdparty.saker.util.thread

public static final class ThreadUtils.ParallelRunner

saker.build.thirdparty.saker.util.thread.ThreadUtils.ParallelRunner

java.lang.Object

Builder class for executing various tasks with the specified configuration concurrently.

This class can be used to configure the concurrent execution of some specified tasks. The configuration includes setting the appropriate ThreadGroup, the number of threads to use, cancellation monitors, and others.

This class acts as a builder, in the sense that it serves as a configuration entity for the executed tasks. This class is reuseable, meaning that running methods can be called multiple times on it.

All running methods in this class throw ParallelExecutionException if the tasks have failed in any way. The thrown exception can be examined to determine the real cause of the exception.

Some of the methods have simplified corresponding functions in ThreadUtils that use the default configuration for the execution, and require no ParallelRunner instance.

Note, that although this class is designed to run tasks concurrently, that doesn't always imply that the posted tasks will run concurrently. E.g. if only a single task needs to run, it will be executed on the current thread without creating a new one for it.

The class supports running simple Runnables concurrently. In that case they will have no extra handling by the executor, and they will simply run concurrently. See runRunnables(Runnable...).

The class supports running tasks concurrently for given work items. The work items will be passed to the given worker tasks which should use the passed argument to do their work on it. See runItems(T[], ThrowingConsumer<? super T>).

The class supports running tasks concurrently for given work items, and using thread specific context objects. The context objects are allocated for each worker thread and will be passed to the worker task alongsite the work item. The context objects can be used as a cache, in order to reduce the amount of object allocations, or others. Note, that even though context objects are cached, the tasks should work properly even if a new context object is allocated for each invocation. See runContextItems(T[], Supplier<? extends C>, ThrowingContextConsumer<? super T, ? super C>).

The items in the runner methods may be specified by a Supplier instance. In that case the supplier will be repeatedly called and new tasks will be started for the results, until a null is returned by the Supplier. The supplier must return a null eventually, else an infinite number of tasks will be started, which most likely deadlock the whole operating system or crash the JVM. (As this can result creating possibly infinite number of threads.)

The run methods in this class supports the throwing of ParallelExecutionAbortedException. If a worker function throws such an exception, the further execution of tasks will be cancelled, and the exception will be thrown to the caller.

Use parallelRunner() to instantiate a new builder.

Methods

public <T, C> void	runContextItems(Iterable<? extends T> items, Supplier<? extends C> contextsupplier, ThrowingContextConsumer<? super T, ? super C> worker) Runs the specified worker function for the given items and using the created context objects.
public <T, C> void	runContextItems(Iterator<? extends T> items, Supplier<? extends C> contextsupplier, ThrowingContextConsumer<? super T, ? super C> worker) Runs the specified worker function for the given items and using the created context objects.
public <T, C> void	runContextItems(Supplier<? extends T> items, Supplier<? extends C> contextsupplier, ThrowingContextConsumer<? super T, ? super C> worker) Runs the specified worker function for the given items and using the created context objects.
public <T, C> void	runContextItems(T[] items, Supplier<? extends C> contextsupplier, ThrowingContextConsumer<? super T, ? super C> worker) Runs the specified worker function for the given items and using the created context objects.
public <T> void	runItems(Iterable<? extends T> items, ThrowingConsumer<? super T> worker) Runs the specified worker function for the given items.
public <T> void	runItems(Iterator<? extends T> items, ThrowingConsumer<? super T> worker) Runs the specified worker function for the given items.
public <T> void	runItems(Supplier<? extends T> items, ThrowingConsumer<? super T> worker) Runs the specified worker function for the given items.
public <T> void	runItems(T[] items, ThrowingConsumer<? super T> worker) Runs the specified worker function for the given items.
public void	runRunnables(Iterable<? extends Runnable> runnables) Runs the argument runnables concurrently.
public void	runRunnables(Iterator<? extends Runnable> runnables) Runs the argument runnables concurrently.
public void	runRunnables(Supplier<? extends Runnable> runnables) Runs the argument runnables concurrently.
public void	runRunnables(Runnable... runnables) Runs the argument runnables concurrently.
public ParallelRunner	setMonitor(OperationCancelMonitor monitor) Sets the cancellation monitor for the running.
public ParallelRunner	setNamePrefix(String namePrefix) Sets the name prefix that should be used for any started threads.
public ParallelRunner	setThreadCount(int threadCount) Sets the thread count that should be used when running multiple tasks concurrently.
public ParallelRunner	setThreadGroup(ThreadGroup threadGroup) Sets the thread group that should be used when starting new threads.

Inherited methods
From: Object clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

public <T, C> void runContextItems(Iterable<? extends T> items, Supplier<? extends C> contextsupplier, ThrowingContextConsumer<? super T, ? super C> worker) throws ParallelExecutionException

Runs the specified worker function for the given items and using the created context objects.

See ParallelRunner documentation for more info.

TThe type of the items.

CThe type of the context object.

itemsThe items to run the worker for.

contextsupplierThe context supplier to create the context object for the workers.

workerThe worker function to run for each item.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public <T, C> void runContextItems(Iterator<? extends T> items, Supplier<? extends C> contextsupplier, ThrowingContextConsumer<? super T, ? super C> worker) throws ParallelExecutionException

Runs the specified worker function for the given items and using the created context objects.

See ParallelRunner documentation for more info.

TThe type of the items.

CThe type of the context object.

itemsThe items to run the worker for.

contextsupplierThe context supplier to create the context object for the workers.

workerThe worker function to run for each item.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public <T, C> void runContextItems(Supplier<? extends T> items, Supplier<? extends C> contextsupplier, ThrowingContextConsumer<? super T, ? super C> worker) throws ParallelExecutionException

Runs the specified worker function for the given items and using the created context objects.

See ParallelRunner documentation for more info.

Warning: The argument supplier must return a null result eventually, else an infinite number of tasks will be started.

TThe type of the items.

CThe type of the context object.

itemsThe items to run the worker for.

contextsupplierThe context supplier to create the context object for the workers.

workerThe worker function to run for each item.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public <T, C> void runContextItems(T[] items, Supplier<? extends C> contextsupplier, ThrowingContextConsumer<? super T, ? super C> worker) throws ParallelExecutionException

Runs the specified worker function for the given items and using the created context objects.

See ParallelRunner documentation for more info.

TThe type of the items.

CThe type of the context object.

itemsThe items to run the worker for.

contextsupplierThe context supplier to create the context object for the workers.

workerThe worker function to run for each item.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public <T> void runItems(Iterable<? extends T> items, ThrowingConsumer<? super T> worker) throws ParallelExecutionException

Runs the specified worker function for the given items.

See ParallelRunner documentation for more info.

TThe type of the items.

itemsThe items to run the worker for.

workerThe worker function to run for each item.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public <T> void runItems(Iterator<? extends T> items, ThrowingConsumer<? super T> worker) throws ParallelExecutionException

Runs the specified worker function for the given items.

See ParallelRunner documentation for more info.

TThe type of the items.

itemsThe items to run the worker for.

workerThe worker function to run for each item.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public <T> void runItems(Supplier<? extends T> items, ThrowingConsumer<? super T> worker) throws ParallelExecutionException

Runs the specified worker function for the given items.

See ParallelRunner documentation for more info.

Warning: The argument supplier must return a null result eventually, else an infinite number of tasks will be started.

TThe type of the items.

itemsThe items to run the worker for.

workerThe worker function to run for each item.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public <T> void runItems(T[] items, ThrowingConsumer<? super T> worker) throws ParallelExecutionException

Runs the specified worker function for the given items.

See ParallelRunner documentation for more info.

TThe type of the items.

itemsThe items to run the worker for.

workerThe worker function to run for each item.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public void runRunnables(Iterable<? extends Runnable> runnables) throws ParallelExecutionException

Runs the argument runnables concurrently.

See ParallelRunner documentation for more info.

runnablesThe runnables to run.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public void runRunnables(Iterator<? extends Runnable> runnables) throws ParallelExecutionException

Runs the argument runnables concurrently.

See ParallelRunner documentation for more info.

runnablesThe runnables to run.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public void runRunnables(Supplier<? extends Runnable> runnables) throws ParallelExecutionException

Runs the argument runnables concurrently.

See ParallelRunner documentation for more info.

Warning: The argument supplier must return a null result eventually, else an infinite number of tasks will be started.

runnablesThe runnables to run.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public void runRunnables(Runnable... runnables) throws ParallelExecutionException

Runs the argument runnables concurrently.

See ParallelRunner documentation for more info.

runnablesThe runnables to run.

ParallelExecutionExceptionIf the execution is cancelled, or the runnables throw an exception.

public ParallelRunner setMonitor(OperationCancelMonitor monitor)

Sets the cancellation monitor for the running.

If the cancellation monitor returns true from OperationCancelMonitor.isCancelled(), the running will abort, and an ParallelExecutionCancelledException will be thrown.

monitorCancellation monitor for the tasks. May be null.

this

public ParallelRunner setNamePrefix(String namePrefix)

Sets the name prefix that should be used for any started threads.

namePrefixThe name prefix to use for each created thread. Recommended format is "Something-". A thread number identifier will be appended to it by the runner.

this

public ParallelRunner setThreadCount(int threadCount)

Sets the thread count that should be used when running multiple tasks concurrently.

Negative values mean the default value.

0 or 1 means that no threads should be spawned, and all run tasks should use the caller thread.

Any other values mean that at most that amount of threads can be spawned to run the tasks.

threadCountThe thread count.

this

public ParallelRunner setThreadGroup(ThreadGroup threadGroup)

Sets the thread group that should be used when starting new threads.

Note, that the tasks are not always executed on a thread that is running in the given thread group, so worker functions shouldn't rely on the thread group being a specific instance. See ParallelRunner documentation for examples.

threadGroupThe thread group or null to use the same thread group as the caller thread. (The caller which calls the run methods, not the caller that calls this method.)

this