org.forgerock.openam.shared.concurrency

Class ThreadMonitor

java.lang.Object

org.forgerock.openam.shared.concurrency.ThreadMonitor

public class ThreadMonitor
extends Object

ThreadMonitor is a utility class responsible for providing a small framework to ensuring that a thread is re-started in the case of an unexpected failure. This framework aims to support a common problem for scheduled threads where a runtime exception is thrown which kills the thread and results in it not being rescheduled. This framework can also be used for standard runnable threads which operate in a loop and expect to stay in that loop. This framework will detect the abnormal thread exit, and reschedule the thread to be executed again. This behaviour will continue until system shutdown is signalled, or the thread exits in the expected fashion of returning from the run method. In the case of scheduled threads (scheduleAtFixedRate for example) the same applies however the thread will never exit normally until it is cancelled. This function is to be used when the caller requires that their thread never fails under any unexpected circumstance. This usage however should be used carefully. ThreadMonitor will monitor failures in the thread it is monitoring and will prevent tight loops by waiting increasing amounts of time between each retry. This amount of time will be called the recovery delay. The recovery delay is computed by multiplying the previous delay by two until it reaches the max recovery delay. As the purpose of the thread is still to be running all the time, the max recovery delay will be short: by printing regular errors, it will remind a problem needs to be address shortly. This will avoid the side effects produced by rapidly failing threads (like filling up log files) whilst still highlighting the critical issue to an administrator. The ThreadMonitor will use its own internal WatchDog class, itself runnable and a thread pool to provide the monitoring.
Thread Policy
: All Runnable tasks provided to this ThreadMonitor should respond to the standard Thread.interrupt() signal. This mechanism will be used for coordinating shutdown of the task. All ExecutorServices provided to this framework are assumed to respond to the system shutdown signal, though this is not required for this framework to function. Sadly though the question of "Who will guard the guards themselves?" is intentionally avoided by this class and should be considered out of scope.

See Also:

ShutdownManager, ShutdownManager

Constructor Summary

Constructors

Constructor and Description
ThreadMonitor(ExecutorService workPool, org.forgerock.util.thread.listener.ShutdownManager shutdownManager, Debug debug) Create an instance of the ThreadMonitor with an assigned work pool of threads to use.
ThreadMonitor(ExecutorService workPool, org.forgerock.util.thread.listener.ShutdownManager shutdownManager, Debug debug, int maxRecoveryDelayInMS, int recoveryDelayDeltaInMS) A constructor reserved for test.

Method Summary

Modifier and Type	Method and Description
int	getSuccessiveFailingCounter() Get Successive failing counter for the test.
void	watchScheduledThread(ScheduledExecutorService scheduledService, Runnable runnable, long delay, long duration, TimeUnit timeUnit) Triggers the given runnable immediately to be executed at the scheduled time.
void	watchThread(ExecutorService service, Runnable runnable) Triggers the given runnable to be executed immediately via the given ExecutorService.

Methods inherited from class java.lang.Object

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

Constructor Detail

ThreadMonitor

@Inject
public ThreadMonitor(ExecutorService workPool,
                             org.forgerock.util.thread.listener.ShutdownManager shutdownManager,
                             @Named(value="amThreadManager")
                             Debug debug)

Create an instance of the ThreadMonitor with an assigned work pool of threads to use.

Parameters:

workPool - A sized ExecutorService which is larger enough to handle the expected number of jobs it needs to monitor. This ExecutorService should be generated using the ExecutorServiceFactory to ensure it responds to the global System Shutdown event. Non null.

shutdownManager - Required to detect shutdown signals.

debug - Non null, required for signalling thread failure/restart.

See Also:

ExecutorServiceFactory

ThreadMonitor

public ThreadMonitor(ExecutorService workPool,
                     org.forgerock.util.thread.listener.ShutdownManager shutdownManager,
                     @Named(value="amThreadManager")
                     Debug debug,
                     int maxRecoveryDelayInMS,
                     int recoveryDelayDeltaInMS)

A constructor reserved for test. We need to trick the time so tests doesn't consume time.

Parameters:

workPool - A sized ExecutorService which is larger enough to handle the expected number of jobs it needs to monitor. This ExecutorService should be generated using the ExecutorServiceFactory to ensure it responds to the global System Shutdown event. Non null.

shutdownManager - Required to detect shutdown signals.

debug - Non null, required for signalling thread failure/restart.

maxRecoveryDelayInMS - Max recovery delay in ms

recoveryDelayDeltaInMS - Recovery delay delta in ms

See Also:

ExecutorServiceFactory

Method Detail

watchThread

public void watchThread(ExecutorService service,
                        Runnable runnable)

Triggers the given runnable to be executed immediately via the given ExecutorService. This will also generate a WatchDog thread to monitor the runnable and detect when it fails abnormally. This will trigger the restart of the thread.

Parameters:

service - Non null service which will hold the runnable.

runnable - Non null runnable to execute immediately.

watchScheduledThread

public void watchScheduledThread(ScheduledExecutorService scheduledService,
                                 Runnable runnable,
                                 long delay,
                                 long duration,
                                 TimeUnit timeUnit)

Triggers the given runnable immediately to be executed at the scheduled time. This will also generate a WatchDog thread to monitor the runnable and detect when it fails abnormally. This will trigger the restart of the thread.

Parameters:

scheduledService - Non null scheduled service which will hold the runnable.

runnable - Non null runnable to executed on a scheduled basis.

delay - Start delay in the given TimeUnits.

duration - Fixed delay in the given TimeUnits.

timeUnit - TimeUnit for both delay and duration.

See Also:

ScheduledExecutorService.scheduleAtFixedRate(Runnable, long, long, java.util.concurrent.TimeUnit)

getSuccessiveFailingCounter

public int getSuccessiveFailingCounter()

Get Successive failing counter for the test.

Returns:

Successive failing counter