Interface RunWithConcurrency
-
public interface RunWithConcurrency
Parameters forParallelUtil.runWithConcurrency(RunWithConcurrency)
.Create an instance by using the
Builder
.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
RunWithConcurrency.Builder
-
Field Summary
Fields Modifier and Type Field Description static long
DEFAULT_MAX_NUMBER_OF_RETRIES
Default value for how often a task is retried before giving up.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description static RunWithConcurrency.Builder
builder()
Returns a newRunWithConcurrency.Builder
.int
concurrency()
The maximum concurrency for running the tasks.default @Nullable java.util.concurrent.ExecutorService
executor()
The executor that will run the tasks.default boolean
forceUsageOfExecutor()
This setting is only relevant if theconcurrency()
is 1.default long
maxWaitRetries()
If theexecutor()
is not able to accept any more tasks, we will wait and retry submitting the task.default boolean
mayInterruptIfRunning()
If theterminationFlag()
triggers or the calling thread isinterrupted
, all running tasks are cancelled.default void
run()
Try to run all tasks for their side effects using at mostconcurrency()
threads at once.java.util.Iterator<? extends java.lang.Runnable>
tasks()
The tasks that will be executed.default TerminationFlag
terminationFlag()
Provide aTerminationFlag
to support graceful early termination.default void
validate()
default long
waitNanos()
The actual wait time in nanoseconds.default long
waitTime()
If theexecutor()
is not able to accept any more tasks, we will wait and retry submitting the task.default java.util.concurrent.TimeUnit
waitTimeUnit()
If theexecutor()
is not able to accept any more tasks, we will wait and retry submitting the task.
-
-
-
Field Detail
-
DEFAULT_MAX_NUMBER_OF_RETRIES
static final long DEFAULT_MAX_NUMBER_OF_RETRIES
Default value for how often a task is retried before giving up. The default is so that retryingevery
microsecond
will stop after about 3 days.- See Also:
maxWaitRetries()
, Constant Field Values
-
-
Method Detail
-
concurrency
int concurrency()
The maximum concurrency for running the tasks.If the concurrency is 1, the tasks are run sequentially on the calling thread until all tasks are finished or the first Exception is thrown. This behavior can be overridden by setting
forceUsageOfExecutor()
totrue
.
-
tasks
java.util.Iterator<? extends java.lang.Runnable> tasks()
The tasks that will be executed.The tasks are submitted to the
executor()
only if they can be immediately scheduled and executed. The iterator is only iterated to at most one item in advance. If the task iterator creates the tasks lazily upon iteration, we can avoid creating all tasks upfront. We can support thousands, even millions of tasks without resource exhaustion that way.We will try to submit tasks as long as no more than
concurrency()
are already started and then continue to submit tasks one-by-one, after a previous tasks has finished, so that no more thanconcurrency
tasks are running in the providedexecutor
.We will try to submit tasks as long as the
executor
can directly start new tasks, that is, we want to avoid creating tasks and put them into the waiting queue if it may never be executed afterwards.
-
forceUsageOfExecutor
@Default default boolean forceUsageOfExecutor()
This setting is only relevant if theconcurrency()
is 1.If
forceUsageOfExecutor
istrue
, we will submit all tasks to the executor. IfforceUsageOfExecutor
isfalse
, we will run all tasks on the calling thread.Running tasks on the calling thread will exit early once an exception is thrown from a task. Running tasks on the executor will collect all exceptions and run all non failing tasks.
The default value is
false
and will let tasks run on the calling thread.
-
waitTime
@Default default long waitTime()
If theexecutor()
is not able to accept any more tasks, we will wait and retry submitting the task. The time to wait is set bywaitTime
together withwaitTimeUnit()
. The number of retries is set bymaxWaitRetries()
.After
maxWaitRetries
have been exhausted, execution of all further tasks is abandoned and aIllegalThreadStateException
is thrown.The default is to retry every 1 microsecond for about 3 days.
-
waitTimeUnit
@Default default java.util.concurrent.TimeUnit waitTimeUnit()
If theexecutor()
is not able to accept any more tasks, we will wait and retry submitting the task. The time to wait is set bywaitTime()
together withwaitTimeUnit
. The number of retries is set bymaxWaitRetries()
.After
maxWaitRetries
have been exhausted, execution of all further tasks is abandoned and aIllegalThreadStateException
is thrown.The default is to retry every 1 microsecond for about 3 days.
-
waitNanos
@Derived default long waitNanos()
The actual wait time in nanoseconds.- See Also:
waitTime()
,waitTimeUnit()
-
maxWaitRetries
@Default default long maxWaitRetries()
If theexecutor()
is not able to accept any more tasks, we will wait and retry submitting the task. The time to wait is set bywaitTime
together withwaitTimeUnit()
. The number of retries is set bymaxWaitRetries
.After
maxWaitRetries
have been exhausted, execution of all further tasks is abandoned and aIllegalThreadStateException
is thrown.The default is to retry every 1 microsecond for about 3 days.
-
terminationFlag
@Default default TerminationFlag terminationFlag()
Provide aTerminationFlag
to support graceful early termination.After the initial number of
concurrency()
tasks have been submitted, the termination flag is checked before submitting any further tasks. If the termination flag triggers, running tasks are asked to stop and outstanding tasks will be abandoned.It is up to the task implementation to also respect the termination flag.
The default flag will never trigger.
-
mayInterruptIfRunning
@Default default boolean mayInterruptIfRunning()
If theterminationFlag()
triggers or the calling thread isinterrupted
, all running tasks are cancelled. This flag is passed toFuture.cancel(boolean)
.If
mayInterruptIfRunning
istrue
, running tasks are interrupted and may exit early if theInterruptedException
is handled properly. IfmayInterruptIfRunning
isfalse
, running tasks are allowed to finish on their own.In either case, tasks that have not been started will never start.
The default behavior is to let tasks continue and not interrupt them.
-
executor
@Default @Nullable default @Nullable java.util.concurrent.ExecutorService executor()
The executor that will run the tasks.If the executor is terminated, tasks are run on the calling thread, even for
concurrencies
greater than 1.If
forceUsageOfExecutor()
istrue
however, anIllegalArgumentException
is thrown when this object is constructed.The default executor is
Pools.DEFAULT
.
-
run
default void run()
Try to run all tasks for their side effects using at mostconcurrency()
threads at once.
-
builder
static RunWithConcurrency.Builder builder()
Returns a newRunWithConcurrency.Builder
.
-
validate
@Check default void validate()
-
-