org.iota.jota.utils.thread

Class BoundedScheduledExecutorService

java.lang.Object

org.iota.jota.utils.thread.BoundedScheduledExecutorService

All Implemented Interfaces:

Executor, ExecutorService, ScheduledExecutorService, ReportingExecutorService, SilentScheduledExecutorService

Direct Known Subclasses:

DedicatedScheduledExecutorService

public class BoundedScheduledExecutorService
extends Object
implements SilentScheduledExecutorService, ReportingExecutorService

This class represents a SilentScheduledExecutorService that accepts only a pre-defined amount of tasks that can be queued or executed at the same time. All tasks exceeding the defined limit will be ignored (instead of being queued) by either throwing a RejectedExecutionException or returning null depending on the method we call (non-silent vs silent).

Whenever a non-recurring task finishes (or a recurring one is cancelled through its Future), it makes space for a new task. This is useful for classes like the com.iota.iri.utils.log.interval.IntervalLogger that want to delay an action if and only if there is no other delayed action queued already.

Note: In contrast to other existing implementations like the SizedScheduledExecutorService of the apache package, this class is thread-safe and will only allow to spawn and queue the exact amount of tasks defined during its creation (since it does not rely on approximate numbers like the queue size).

Constructor Summary

Constructors

Constructor and Description
BoundedScheduledExecutorService(int capacity) Creates an executor service that that accepts only a pre-defined amount of tasks that can be queued and run at the same time. All tasks exceeding the defined limit will be ignored (instead of being queued) by either throwing a RejectedExecutionException or returning null depending on the method we call (non-silent vs silent).

Method Summary

Modifier and Type	Method and Description
boolean	awaitTermination(long timeout, TimeUnit unit)
void	execute(Runnable command)
<T> List<Future<T>>	invokeAll(Collection<? extends Callable<T>> tasks)
<T> List<Future<T>>	invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
<T> T	invokeAny(Collection<? extends Callable<T>> tasks)
<T> T	invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
boolean	isShutdown()
boolean	isTerminated()
void	onCancelTask(TaskDetails taskDetails) This method gets called whenever a task is cancelled through its Future or through the shutdown methods of the ExecutorService. It only gets called once for every task.
void	onCompleteTask(TaskDetails taskDetails, Throwable error) This method gets called whenever a task completes. This can be through either raising an exception, cancelling from the outside or by simply terminating in a normal manner.
void	onFinishTask(TaskDetails taskDetails, Throwable error) This method gets called whenever a task is finished. For recurring tasks it is called multiple times.
void	onScheduleTask(TaskDetails taskDetails) This method gets called whenever a new task is scheduled to run. In contrast to ReportingExecutorService.onStartTask(TaskDetails) this method gets called only once for "recurring" tasks that are scheduled to run in pre-defined intervals.
void	onStartTask(TaskDetails taskDetails) This method gets called whenever a task is started. For recurring tasks it is called multiple times.
<V> ScheduledFuture<V>	schedule(Callable<V> callable, long delay, TimeUnit unit)
ScheduledFuture<?>	schedule(Runnable command, long delay, TimeUnit unit)
ScheduledFuture<?>	scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)
ScheduledFuture<?>	scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit)
void	shutdown() In addition to delegating the method call to the internal ScheduledExecutorService, we call the cancel logic for recurring tasks because shutdown prevents them from firing again.
List<Runnable>	shutdownNow() Before delegating the method call to the internal ScheduledExecutorService, we call the onCancelTask(TaskDetails) callback for all scheduled tasks and fire the onCompleteTask(TaskDetails, Throwable) callback for all tasks that are not being executed right now (otherwise this will be fired inside the wrapped task).
void	silentExecute(Runnable task) Does the same as Executor.execute(Runnable) but doesn't throw a RejectedExecutionException if this task cannot be accepted for execution.
<T> List<Future<T>>	silentInvokeAll(Collection<? extends Callable<T>> tasks) Does the same as ExecutorService.invokeAll(Collection) but returns null instead of throwing a RejectedExecutionException if any task cannot be scheduled for execution.
<T> List<Future<T>>	silentInvokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) Does the same as ExecutorService.invokeAll(Collection, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if any task cannot be scheduled for execution.
<T> T	silentInvokeAny(Collection<? extends Callable<T>> tasks) Does the same as ExecutorService.invokeAny(Collection) but returns null instead of throwing a RejectedExecutionException if tasks cannot be scheduled for execution.
<T> T	silentInvokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) Does the same as ExecutorService.invokeAny(Collection, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if tasks cannot be scheduled for execution.
<V> ScheduledFuture<V>	silentSchedule(Callable<V> task, long delay, TimeUnit unit) Does the same as ScheduledExecutorService.schedule(Callable, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.
ScheduledFuture<?>	silentSchedule(Runnable task, long delay, TimeUnit unit) Does the same as ScheduledExecutorService.schedule(Runnable, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.
ScheduledFuture<?>	silentScheduleAtFixedRate(Runnable task, long initialDelay, long period, TimeUnit unit) Does the same as ScheduledExecutorService.scheduleAtFixedRate(Runnable, long, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.
ScheduledFuture<?>	silentScheduleWithFixedDelay(Runnable task, long initialDelay, long delay, TimeUnit unit) Does the same as ScheduledExecutorService.scheduleWithFixedDelay(Runnable, long, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.
<T> Future<T>	silentSubmit(Callable<T> task) Does the same as ExecutorService.submit(Callable) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.
Future<?>	silentSubmit(Runnable task) Does the same as ExecutorService.submit(Runnable) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.
<T> Future<T>	silentSubmit(Runnable task, T result) Does the same as ExecutorService.submit(Runnable, Object) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.
<T> Future<T>	submit(Callable<T> task)
Future<?>	submit(Runnable task)
<T> Future<T>	submit(Runnable task, T result)

Methods inherited from class java.lang.Object

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

Constructor Detail

BoundedScheduledExecutorService

public BoundedScheduledExecutorService(int capacity)

Creates an executor service that that accepts only a pre-defined amount of tasks that can be queued and run at the same time.

All tasks exceeding the defined limit will be ignored (instead of being queued) by either throwing a RejectedExecutionException or returning null depending on the method we call (non-silent vs silent).

Parameters:

capacity - the amount of tasks that can be scheduled simultaneously

Method Detail

onScheduleTask

public void onScheduleTask(TaskDetails taskDetails)

This method gets called whenever a new task is scheduled to run.

In contrast to ReportingExecutorService.onStartTask(TaskDetails) this method gets called only once for "recurring" tasks that are scheduled to run in pre-defined intervals.

It simply adds the task to the internal set of scheduled tasks.

Specified by:

onScheduleTask in interface ReportingExecutorService

Parameters:

taskDetails - object containing details about this task

onStartTask

public void onStartTask(TaskDetails taskDetails)

Description copied from interface: ReportingExecutorService

This method gets called whenever a task is started.

For recurring tasks it is called multiple times.

Specified by:

onStartTask in interface ReportingExecutorService

Parameters:

taskDetails - object containing details about this task

onFinishTask

public void onFinishTask(TaskDetails taskDetails,
                         Throwable error)

Description copied from interface: ReportingExecutorService

This method gets called whenever a task is finished.

For recurring tasks it is called multiple times.

Specified by:

onFinishTask in interface ReportingExecutorService

Parameters:

taskDetails - object containing details about this task

error - Exception that caused the task to complete

onCancelTask

public void onCancelTask(TaskDetails taskDetails)

Description copied from interface: ReportingExecutorService

This method gets called whenever a task is cancelled through its Future or through the shutdown methods of the ExecutorService.

It only gets called once for every task.

Specified by:

onCancelTask in interface ReportingExecutorService

Parameters:

taskDetails - object containing details about this task

onCompleteTask

public void onCompleteTask(TaskDetails taskDetails,
                           Throwable error)

This method gets called whenever a task completes.

This can be through either raising an exception, cancelling from the outside or by simply terminating in a normal manner. For recurring tasks this only gets called once.

It frees the reserved resources by decrementing the scheduledTasksCounter and removing the task from the scheduledTasks set.

Specified by:

onCompleteTask in interface ReportingExecutorService

Parameters:

taskDetails - object containing details about this task

error - Exception that caused the task to complete

silentSchedule

public ScheduledFuture<?> silentSchedule(Runnable task,
                                         long delay,
                                         TimeUnit unit)

Does the same as ScheduledExecutorService.schedule(Runnable, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.

Note: Since the ScheduledFuture returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned ScheduledFuture AND the Runnable to correctly free the resources if its Future.cancel(boolean) method is called.

Specified by:

silentSchedule in interface SilentScheduledExecutorService

Parameters:

task - the task to execute

delay - the time from now to delay execution

unit - the time unit of the delay parameter

Returns:

a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion / null if the task cannot be scheduled for execution

silentSchedule

public <V> ScheduledFuture<V> silentSchedule(Callable<V> task,
                                             long delay,
                                             TimeUnit unit)

Does the same as ScheduledExecutorService.schedule(Callable, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.

Note: Since the ScheduledFuture returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned ScheduledFuture AND the Callable to correctly free the resources if its Future.cancel(boolean) method is called.

Specified by:

silentSchedule in interface SilentScheduledExecutorService

Type Parameters:

V - the type of the callable's result

Parameters:

task - the function to execute

delay - the time from now to delay execution

unit - the time unit of the delay parameter

Returns:

a ScheduledFuture that can be used to extract result or cancel / null if the task cannot be scheduled for execution

silentScheduleAtFixedRate

public ScheduledFuture<?> silentScheduleAtFixedRate(Runnable task,
                                                    long initialDelay,
                                                    long period,
                                                    TimeUnit unit)

Does the same as ScheduledExecutorService.scheduleAtFixedRate(Runnable, long, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.

Note: Since the ScheduledFuture returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned ScheduledFuture AND the Runnable to correctly free the resources if its Future.cancel(boolean) method is called.

Specified by:

silentScheduleAtFixedRate in interface SilentScheduledExecutorService

Parameters:

task - the task to execute

initialDelay - the time to delay first execution

period - the period between successive executions

unit - the time unit of the initialDelay and period parameters

Returns:

a ScheduledFuture representing pending completion of the task, and whose get() method will throw an exception upon cancellation / null if the task cannot be scheduled for execution

silentScheduleWithFixedDelay

public ScheduledFuture<?> silentScheduleWithFixedDelay(Runnable task,
                                                       long initialDelay,
                                                       long delay,
                                                       TimeUnit unit)

Does the same as ScheduledExecutorService.scheduleWithFixedDelay(Runnable, long, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.

Note: Since the ScheduledFuture returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned ScheduledFuture AND the Runnable to correctly free the resources if its Future.cancel(boolean) method is called.

Specified by:

silentScheduleWithFixedDelay in interface SilentScheduledExecutorService

Parameters:

task - the task to execute

initialDelay - the time to delay first execution

delay - the delay between the termination of one execution and the commencement of the next

unit - the time unit of the initialDelay and delay parameters

Returns:

a ScheduledFuture representing pending completion of the task, and whose get() method will throw an exception upon cancellation / null if the task cannot be scheduled for execution

silentSubmit

public <T> Future<T> silentSubmit(Callable<T> task)

Does the same as ExecutorService.submit(Callable) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.

Note: Since the Future returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned Future AND the Callable to correctly free the resources if its Future.cancel(boolean) method is called.

Specified by:

silentSubmit in interface SilentScheduledExecutorService

Type Parameters:

T - the type of the task's result

Parameters:

task - the task to submit

Returns:

a Future representing pending completion of the task / null if the task cannot be scheduled for execution

silentSubmit

public Future<?> silentSubmit(Runnable task)

Does the same as ExecutorService.submit(Runnable) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.

Note: Since the Future returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned Future AND the Runnable to correctly free the resources if its Future.cancel(boolean) method is called.

Specified by:

silentSubmit in interface SilentScheduledExecutorService

Parameters:

task - the task to submit

Returns:

a Future representing pending completion of the task / null if the task cannot be scheduled for execution

silentSubmit

public <T> Future<T> silentSubmit(Runnable task,
                                  T result)

Does the same as ExecutorService.submit(Runnable, Object) but returns null instead of throwing a RejectedExecutionException if the task cannot be scheduled for execution.

Note: Since the Future returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned Future AND the Runnable to correctly free the resources if its Future.cancel(boolean) method is called.

Specified by:

silentSubmit in interface SilentScheduledExecutorService

Type Parameters:

T - the type of the result

Parameters:

task - the task to submit

result - the result to return

Returns:

a Future representing pending completion of the task / null if the task cannot be scheduled for execution

silentInvokeAll

public <T> List<Future<T>> silentInvokeAll(Collection<? extends Callable<T>> tasks)
                                    throws InterruptedException

Does the same as ExecutorService.invokeAll(Collection) but returns null instead of throwing a RejectedExecutionException if any task cannot be scheduled for execution.

Note: Since the Futures will all be finished (and cannot be cancelled anymore) when the underlying method returns, we only wrap the Callables to correctly free the resources and omit wrapping the returned Futures.

Specified by:

silentInvokeAll in interface SilentScheduledExecutorService

Type Parameters:

T - the type of the values returned from the tasks

Parameters:

tasks - the collection of tasks

Returns:

a list of Futures representing the tasks, in the same sequential order as produced by the iterator for the given task list, each of which has completed / null if any task cannot be scheduled for execution

Throws:

InterruptedException - if interrupted while waiting, in which case unfinished tasks are cancelled

silentInvokeAll

public <T> List<Future<T>> silentInvokeAll(Collection<? extends Callable<T>> tasks,
                                           long timeout,
                                           TimeUnit unit)
                                    throws InterruptedException

Does the same as ExecutorService.invokeAll(Collection, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if any task cannot be scheduled for execution.

Note: Since the Futures will all be finished (and cannot be cancelled anymore) when the underlying method returns, we only wrap the Callables to correctly free the resources and omit wrapping the returned Futures.

Specified by:

silentInvokeAll in interface SilentScheduledExecutorService

Type Parameters:

T - the type of the values returned from the tasks

Parameters:

tasks - the collection of tasks

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

a list of Futures representing the tasks, in the same sequential order as produced by the iterator for the given task list. If the operation did not time out, each task will have completed. If it did time out, some of these tasks will not have completed. It returns null if any task cannot be scheduled for execution.

Throws:

InterruptedException - if interrupted while waiting, in which case unfinished tasks are cancelled

silentInvokeAny

public <T> T silentInvokeAny(Collection<? extends Callable<T>> tasks)
                      throws InterruptedException,
                             ExecutionException

Does the same as ExecutorService.invokeAny(Collection) but returns null instead of throwing a RejectedExecutionException if tasks cannot be scheduled for execution.

Note: Since the Futures are not passed to the caller, we only wrap the Callables to correctly free the resources and omit wrapping the Futures as well.

Specified by:

silentInvokeAny in interface SilentScheduledExecutorService

Type Parameters:

T - the type of the values returned from the tasks

Parameters:

tasks - the collection of tasks

Returns:

the result returned by one of the tasks or null if tasks cannot be scheduled for execution

Throws:

InterruptedException - if interrupted while waiting

ExecutionException - if no task successfully completes

silentInvokeAny

public <T> T silentInvokeAny(Collection<? extends Callable<T>> tasks,
                             long timeout,
                             TimeUnit unit)
                      throws InterruptedException,
                             ExecutionException,
                             TimeoutException

Does the same as ExecutorService.invokeAny(Collection, long, TimeUnit) but returns null instead of throwing a RejectedExecutionException if tasks cannot be scheduled for execution.

Note: Since the Futures are not passed to the caller, we only wrap the Callables to correctly free the resources and omit wrapping the related Futures as well.

Specified by:

silentInvokeAny in interface SilentScheduledExecutorService

Type Parameters:

T - the type of the values returned from the tasks

Parameters:

tasks - the collection of tasks

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the result returned by one of the tasks or null if tasks cannot be scheduled for execution

Throws:

InterruptedException - if interrupted while waiting

ExecutionException - if no task successfully completes

TimeoutException - if the given timeout elapses before any task successfully completes

silentExecute

public void silentExecute(Runnable task)

Does the same as Executor.execute(Runnable) but doesn't throw a RejectedExecutionException if this task cannot be accepted for execution.

Note: Since there is no Future passed to the caller, we only wrap the Runnable to correctly free the resources.

Specified by:

silentExecute in interface SilentScheduledExecutorService

Parameters:

task - the runnable task

schedule

public ScheduledFuture<?> schedule(Runnable command,
                                   long delay,
                                   TimeUnit unit)

Specified by:

schedule in interface ScheduledExecutorService

schedule

public <V> ScheduledFuture<V> schedule(Callable<V> callable,
                                       long delay,
                                       TimeUnit unit)

Specified by:

schedule in interface ScheduledExecutorService

scheduleAtFixedRate

public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
                                              long initialDelay,
                                              long period,
                                              TimeUnit unit)

Specified by:

scheduleAtFixedRate in interface ScheduledExecutorService

scheduleWithFixedDelay

public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
                                                 long initialDelay,
                                                 long delay,
                                                 TimeUnit unit)

Specified by:

scheduleWithFixedDelay in interface ScheduledExecutorService

submit

public <T> Future<T> submit(Callable<T> task)

Specified by:

submit in interface ExecutorService

submit

public <T> Future<T> submit(Runnable task,
                            T result)

Specified by:

submit in interface ExecutorService

submit

public Future<?> submit(Runnable task)

Specified by:

submit in interface ExecutorService

invokeAll

public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
                              throws InterruptedException

Specified by:

invokeAll in interface ExecutorService

Throws:

InterruptedException

invokeAll

public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks,
                                     long timeout,
                                     TimeUnit unit)
                              throws InterruptedException

Specified by:

invokeAll in interface ExecutorService

Throws:

InterruptedException

invokeAny

public <T> T invokeAny(Collection<? extends Callable<T>> tasks)
                throws InterruptedException,
                       ExecutionException

Specified by:

invokeAny in interface ExecutorService

Throws:

InterruptedException

ExecutionException

invokeAny

public <T> T invokeAny(Collection<? extends Callable<T>> tasks,
                       long timeout,
                       TimeUnit unit)
                throws InterruptedException,
                       ExecutionException,
                       TimeoutException

Specified by:

invokeAny in interface ExecutorService

Throws:

InterruptedException

ExecutionException

TimeoutException

execute

public void execute(Runnable command)

Specified by:

execute in interface Executor

shutdown

public void shutdown()

In addition to delegating the method call to the internal ScheduledExecutorService, we call the cancel logic for recurring tasks because shutdown prevents them from firing again. If these "cancelled" jobs are scheduled for execution (and not running right now), we also call their onCompleteTask(TaskDetails, Throwable) callback to "report" that hey have finished (otherwise this will be fired inside the wrapped task).

Specified by:

shutdown in interface ExecutorService

shutdownNow

public List<Runnable> shutdownNow()

Before delegating the method call to the internal ScheduledExecutorService, we call the onCancelTask(TaskDetails) callback for all scheduled tasks and fire the onCompleteTask(TaskDetails, Throwable) callback for all tasks that are not being executed right now (otherwise this will be fired inside the wrapped task).

Specified by:

shutdownNow in interface ExecutorService

isShutdown

public boolean isShutdown()

Specified by:

isShutdown in interface ExecutorService

isTerminated

public boolean isTerminated()

Specified by:

isTerminated in interface ExecutorService

awaitTermination

public boolean awaitTermination(long timeout,
                                TimeUnit unit)
                         throws InterruptedException

Specified by:

awaitTermination in interface ExecutorService

Throws:

InterruptedException