org.iota.jota.utils.thread

Class DedicatedScheduledExecutorService

java.lang.Object

org.iota.jota.utils.thread.BoundedScheduledExecutorService

org.iota.jota.utils.thread.DedicatedScheduledExecutorService

All Implemented Interfaces:

Executor, ExecutorService, ScheduledExecutorService, ReportingExecutorService, SilentScheduledExecutorService

public class DedicatedScheduledExecutorService
extends BoundedScheduledExecutorService
implements ReportingExecutorService

This class represents a ScheduledExecutorService that is associated with one specific task for which it provides automatic logging capabilities

It informs the user about its lifecycle using the logback loggers used by IRI. In addition it offers "silent" methods of the ScheduledExecutorService that do not throw Exceptions when we try to start the same task multiple times. This is handy for implementing the "start" and "shutdown" methods of the background workers of IRI that would otherwise have to take care of not starting the same task more than once (when trying to be robust against coding errors or tests that start the same thread multiple times).

Constructor Summary

Constructors

Constructor and Description
DedicatedScheduledExecutorService() Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to null for the thread name (which causes only error messages to be printed), the DEFAULT_LOGGER for the log messages and false for the debug flag. Note: This is for example used by the com.iota.iri.utils.log.interval.IntervalLogger which does not want to inform the user when scheduling a log output, but which still needs the "only run one task" logic.
DedicatedScheduledExecutorService(boolean debug) Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to null for the thread name (which causes only error messages to be printed - unless debug is true) and the DEFAULT_LOGGER for the log messages. Note: This is for example used by the com.iota.iri.utils.log.interval.IntervalLogger which does not want to inform the user when scheduling a log output, but which still needs the "only run one task" logic.
DedicatedScheduledExecutorService(org.slf4j.Logger logger) Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to null for the thread name (which causes only error messages to be printed - unless debug is true) and and false for the debug flag. Note: This is for example used by the com.iota.iri.utils.log.interval.IntervalLogger which does not want to inform the user when scheduling a log output, but which still needs the "only run one task" logic.
DedicatedScheduledExecutorService(org.slf4j.Logger logger, boolean debug) Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to null for the thread name (which causes only error messages to be printed - unless debug is true). Note: This is for example used by the com.iota.iri.utils.log.interval.IntervalLogger which does not want to inform the user when scheduling a log output, but which still needs the "only run one task" logic.
DedicatedScheduledExecutorService(String threadName) Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to the DEFAULT_LOGGER for the log messages and false for the debug flag.
DedicatedScheduledExecutorService(String threadName, boolean debug) Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to the DEFAULT_LOGGER for the log messages.
DedicatedScheduledExecutorService(String threadName, org.slf4j.Logger logger) Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to false for the debug flag.
DedicatedScheduledExecutorService(String threadName, org.slf4j.Logger logger, boolean debug) Creates a ScheduledExecutorService that is associated with one specific task for which it provides automatic logging capabilities (using the provided thread name). It informs the user about its lifecycle using the logback loggers used by IRI.

Method Summary

Modifier and Type	Method and Description
String	getThreadName() This method is the getter for the name of the thread that gets created by this service.
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.

Methods inherited from class org.iota.jota.utils.thread.BoundedScheduledExecutorService

awaitTermination, execute, invokeAll, invokeAll, invokeAny, invokeAny, isShutdown, isTerminated, schedule, schedule, scheduleAtFixedRate, scheduleWithFixedDelay, shutdown, shutdownNow, silentExecute, silentInvokeAll, silentInvokeAll, silentInvokeAny, silentInvokeAny, silentSchedule, silentSchedule, silentScheduleAtFixedRate, silentScheduleWithFixedDelay, silentSubmit, silentSubmit, silentSubmit, submit, submit, submit

Methods inherited from class java.lang.Object

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

Constructor Detail

DedicatedScheduledExecutorService

public DedicatedScheduledExecutorService(String threadName,
                                         org.slf4j.Logger logger,
                                         boolean debug)

Creates a ScheduledExecutorService that is associated with one specific task for which it provides automatic logging capabilities (using the provided thread name).

It informs the user about its lifecycle using the logback loggers used by IRI. In addition it offers "silent" methods of the ScheduledExecutorService that do not throw Exceptions when we try to start the same task multiple times. This is handy for implementing the "start" and "shutdown" methods of the background workers of IRI that would otherwise have to take care of not starting the same task more than once (when trying to be robust against coding errors or tests that start the same thread multiple times).

     Example:

         private final static Logger logger = LoggerFactor.getLogger(MilestoneSolidifier.class);

         private DedicatedScheduledExecutorService milestoneSolidifier = new DedicatedScheduledExecutorService(
                 "Solidification Thread", logger, false);

         // calling this multiple times will only start exactly one background job (ignore additional requests)
         public void start() {
             milestoneSolidifier.silentScheduleAtFixedRate(this::solidificationThread, 10, 50, MILLISECONDS);
         }

         // calling this multiple times will only stop the one instance that is running (if it is running)
         public void shutdown() {
             milestoneSolidifier.shutdownNow();
         }

         public void solidificationThread() {
             System.out.println("I get executed every 50 milliseconds");
         }
     
     Resulting Log Output:

         [main] INFO  MilestoneSolidifier - Starting [Milestone Solidifier] (starts in 10ms / runs every 50ms) ...
         [main] INFO  MilestoneSolidifier - [Milestone Solidifier] Started (execution #1) ...
         [Milestone Solidifier] INFO  c.i.i.s.m.MilestoneSolidifier - I get executed every 50 milliseconds
         [Milestone Solidifier] INFO  c.i.i.s.m.MilestoneSolidifier - I get executed every 50 milliseconds
         [Milestone Solidifier] INFO  c.i.i.s.m.MilestoneSolidifier - I get executed every 50 milliseconds
         [main] INFO  MilestoneSolidifier - Stopping [Milestone Solidifier] ...
         [main] INFO  MilestoneSolidifier - [Milestone Solidifier] Stopped (after #4 executions) ...
     

Parameters:

threadName - name of the thread (or null if we want to disable the automatic logging - exceptions will always be logged)

logger - logback logger that shall be used for the origin of the log messages

debug - debug flag that indicates if every "run" should be accompanied with a log message

DedicatedScheduledExecutorService

public DedicatedScheduledExecutorService(String threadName,
                                         boolean debug)

Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to the DEFAULT_LOGGER for the log messages.

Parameters:

threadName - name of the thread (or null if we want to disable the automatic logging - exceptions will always be logged)

debug - debug flag that indicates if every "run" should be accompanied with a log message

DedicatedScheduledExecutorService

public DedicatedScheduledExecutorService(String threadName,
                                         org.slf4j.Logger logger)

Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to false for the debug flag.

Parameters:

threadName - name of the thread (or null if we want to disable the automatic logging - exceptions will always be logged)

logger - logback logger that shall be used for the origin of the log messages

DedicatedScheduledExecutorService

public DedicatedScheduledExecutorService(org.slf4j.Logger logger,
                                         boolean debug)

Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to null for the thread name (which causes only error messages to be printed - unless debug is true).

Note: This is for example used by the com.iota.iri.utils.log.interval.IntervalLogger which does not want to inform the user when scheduling a log output, but which still needs the "only run one task" logic.

Parameters:

logger - logback logger that shall be used for the origin of the log messages

debug - debug flag that indicates if every "run" should be accompanied with a log message

DedicatedScheduledExecutorService

public DedicatedScheduledExecutorService(String threadName)

Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to the DEFAULT_LOGGER for the log messages and false for the debug flag.

Parameters:

threadName - name of the thread (or null if we want to disable the automatic logging - exceptions will always be logged)

DedicatedScheduledExecutorService

public DedicatedScheduledExecutorService(org.slf4j.Logger logger)

Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to null for the thread name (which causes only error messages to be printed - unless debug is true) and and false for the debug flag.

Note: This is for example used by the com.iota.iri.utils.log.interval.IntervalLogger which does not want to inform the user when scheduling a log output, but which still needs the "only run one task" logic.

Parameters:

logger - logback logger that shall be used for the origin of the log messages

DedicatedScheduledExecutorService

public DedicatedScheduledExecutorService(boolean debug)

Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to null for the thread name (which causes only error messages to be printed - unless debug is true) and the DEFAULT_LOGGER for the log messages.

Note: This is for example used by the com.iota.iri.utils.log.interval.IntervalLogger which does not want to inform the user when scheduling a log output, but which still needs the "only run one task" logic.

Parameters:

debug - debug flag that indicates if every "run" should be accompanied with a log message

DedicatedScheduledExecutorService

public DedicatedScheduledExecutorService()

Does the same as DedicatedScheduledExecutorService(String, Logger, boolean) but defaults to null for the thread name (which causes only error messages to be printed), the DEFAULT_LOGGER for the log messages and false for the debug flag.

Note: This is for example used by the com.iota.iri.utils.log.interval.IntervalLogger which does not want to inform the user when scheduling a log output, but which still needs the "only run one task" logic.

Method Detail

getThreadName

public String getThreadName()

This method is the getter for the name of the thread that gets created by this service.

Returns:

it simply returns the private property of threadName.

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.
This method shows a message whenever a task gets successfully scheduled.

We only show the scheduling message if debugging is enabled or a thread name was defined when creating this DedicatedScheduledExecutorService (to not pollute the CLI with meaningless messages).

Specified by:

onScheduleTask in interface ReportingExecutorService

Overrides:

onScheduleTask in class BoundedScheduledExecutorService

Parameters:

taskDetails - metadata holding the relevant information of the task

onStartTask

public void onStartTask(TaskDetails taskDetails)

This method gets called whenever a task is started.

For recurring tasks it is called multiple times.
This method shows a message whenever a task starts to be processed.

We only show the starting message if debug is enabled or if it is the first start of the task in a named DedicatedScheduledExecutorService (display it like it would be a Thread with one start message and one stop message - to not pollute the CLI with meaningless messages).

To increase the information available for debugging, we change the thread name to the one that initiated the start (rather than the randomly assigned one from the executor service) before printing the start message.

After the start message was printed, we set the name of the Thread that will consequently be used for log messages from the task itself.

Specified by:

onStartTask in interface ReportingExecutorService

Overrides:

onStartTask in class BoundedScheduledExecutorService

Parameters:

taskDetails - metadata holding the relevant information of the task

onFinishTask

public void onFinishTask(TaskDetails taskDetails,
                         Throwable error)

This method gets called whenever a task is finished.

For recurring tasks it is called multiple times.
This method shows a message when the task finishes its execution (can happen multiple times for recurring tasks).

We only show the finishing message if debug is enabled and if no error occurred (otherwise the onCompleteTask(TaskDetails, Throwable) callback will give enough information about the crash).

To be consistent with the start message, we change the thread name to the one that initiated the task (this also makes it easier to distinguish log messages that are emitted by the "real" logic of the task from the "automated" messages about its lifecycle).

Specified by:

onFinishTask in interface ReportingExecutorService

Overrides:

onFinishTask in class BoundedScheduledExecutorService

Parameters:

taskDetails - metadata holding the relevant information of the task

error - the exception that caused this task to terminate or null if it terminated normally

onCancelTask

public 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.
This method shows an information about the intent to cancel the task.

We only show the cancel message if debugging is enabled or a thread name was defined when creating this DedicatedScheduledExecutorService (to not pollute the CLI with meaningless messages).

Specified by:

onCancelTask in interface ReportingExecutorService

Overrides:

onCancelTask in class BoundedScheduledExecutorService

Parameters:

taskDetails - metadata holding the relevant information of the 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 BoundedScheduledExecutorService.scheduledTasksCounter and removing the task from the BoundedScheduledExecutorService.scheduledTasks set.
This method shows a stopped message whenever it finally terminates (and doesn't get launched again in case of recurring tasks).

We only show the stopped message if debug is enabled, an exception occurred (always show unexpected errors) or if we have a named DedicatedScheduledExecutorService (to not pollute the CLI with meaningless messages).
If the completion of the task was not caused by an outside call to cancel it, we change the thread name to the one that initiated the task (this makes it easier to distinguish log messages that are emitted by the "real" logic of the task from the "automated" messages about its lifecycle).

Specified by:

onCompleteTask in interface ReportingExecutorService

Overrides:

onCompleteTask in class BoundedScheduledExecutorService

Parameters:

taskDetails - metadata holding the relevant information of the task

error - the exception that caused this task to terminate or null if it terminated normally