com.sleepycat.je.utilint

Class StoppableThread

java.lang.Object

java.lang.Thread

com.sleepycat.je.utilint.StoppableThread

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

ArbiterImpl, DataEraser, ElectionAgentThread, FeederManager, LogFileFeeder, ReplicaOutputThreadBase, RepNode, ReservedFilesAutoRepair, ServiceDispatcher

public abstract class StoppableThread
extends Thread

A StoppableThread is a daemon that obeys the following mandates: - it sets the daemon property for the thread - an uncaught exception handler is always registered - the thread registers with the JE exception listener mechanism. - its shutdown method can only be executed once. StoppableThreads are not required to implement shutdown() methods, because in some cases their shutdown processing must be coordinated by an owning, parent thread. StoppableThread is an alternative to the DaemonThread. It also assumes that the thread's run() method may be more complex than that of the work-queue, task oriented DaemonThread. A StoppableThread's run method should catch and handle all exceptions. By default, unhandled exceptions are considered programming errors, and invalidate the environment, but StoppableThreads may supply alternative uncaught exception handling. StoppableThreads usually are created with an EnvironmentImpl, but on occasion an environment may not be available (for components that can execute without an environment). In that case, the thread obviously does not invalidate the environment. Note that the StoppableThread.cleanup must be invoked upon, or soon after, thread exit.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field and Description
protected EnvironmentImpl	envImpl

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StoppableThread(EnvironmentImpl envImpl, String threadName)
protected	StoppableThread(EnvironmentImpl envImpl, Thread.UncaughtExceptionHandler handler, Runnable runnable, String threadName)
protected	StoppableThread(EnvironmentImpl envImpl, Thread.UncaughtExceptionHandler handler, String threadName)
protected	StoppableThread(String threadName)

Method Summary

Modifier and Type	Method and Description
protected void	cleanup() Must be invoked upon, or soon after, exit from the thread to perform any cleanup, and ensure that any allocated resources are freed.
protected abstract Logger	getLogger()
Exception	getSavedShutdownException() Returns the exception if any that provoked the shutdown
long	getTotalCpuTime() Returns the total cpu time associated with the thread, after the thread has been shutdown.
long	getTotalUserTime() Returns the total cpu time associated with the thread, after the thread has been shutdown.
static void	handleUncaughtException(Logger useLogger, EnvironmentImpl envImpl, Thread t, Throwable e)
protected int	initiateSoftShutdown() Threads that use shutdownThread() must define this method.
boolean	isShutdown()
void	saveShutdownException(Exception shutdownException)
protected boolean	shutdownDone(Logger logger) If the shutdown flag is false, set it to true and return false; in this case the caller should perform shutdown, including calling shutdownThread(java.util.logging.Logger).
void	shutdownThread(Logger logger) This method is invoked from another thread of control to shutdown this thread.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, run, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

envImpl

protected final EnvironmentImpl envImpl

Constructor Detail

StoppableThread

protected StoppableThread(String threadName)

StoppableThread

protected StoppableThread(EnvironmentImpl envImpl,
                          String threadName)

StoppableThread

protected StoppableThread(EnvironmentImpl envImpl,
                          Thread.UncaughtExceptionHandler handler,
                          String threadName)

StoppableThread

protected StoppableThread(EnvironmentImpl envImpl,
                          Thread.UncaughtExceptionHandler handler,
                          Runnable runnable,
                          String threadName)

Method Detail

getLogger

protected abstract Logger getLogger()

Returns:

a logger to use when logging uncaught exceptions.

getSavedShutdownException

public Exception getSavedShutdownException()

Returns the exception if any that provoked the shutdown

Returns:

the exception, or null if it was a normal shutdown

saveShutdownException

public void saveShutdownException(Exception shutdownException)

isShutdown

public boolean isShutdown()

shutdownDone

protected boolean shutdownDone(Logger logger)

If the shutdown flag is false, set it to true and return false; in this case the caller should perform shutdown, including calling shutdownThread(java.util.logging.Logger). If the shutdown flag is true, wait for this thread to exit and return true; in this case the caller should not perform shutdown. When shutdownDone is initially called by thread X (including from the run method of the thread being shutdown), then a thread Y calling shutdownDone should simply return without performing shutdown (this is when shutdownDone returns true). In this case it is important that this method calls waitForExit(java.util.logging.Logger) in thread Y to ensure that thread X really dies, or that an EnvironmentWedgedException is thrown if X does not die. In particular it is important that all JE threads have died and released their resources when Environment.close returns to the app thread, or that EWE is thrown if any JE threads have not died. This allows the app to reliably re-open the env, or exit the process if necessary. [#25648] Note than when thread X has sub-components and manages their threads, thread X's shutdown method will call shutdown for its managed threads. Waiting for exit of thread X will therefore wait for exit of its managed threads, assuming that all shutdown methods calls shutdownDone as described.

Parameters:

logger - the logger on which to log messages

Returns:

true if shutdown is already set.

cleanup

protected void cleanup()

Must be invoked upon, or soon after, exit from the thread to perform any cleanup, and ensure that any allocated resources are freed.

handleUncaughtException

public static void handleUncaughtException(Logger useLogger,
                                           EnvironmentImpl envImpl,
                                           Thread t,
                                           Throwable e)

shutdownThread

public void shutdownThread(Logger logger)

This method is invoked from another thread of control to shutdown this thread. The method tries shutting down the thread using a variety of techniques, starting with the gentler techniques in order to limit of stopping the thread on the overall process and proceeding to harsher techniques: 1) It first tries a "soft" shutdown by invoking initiateSoftShutdown(). This is the technique of choice. Each StoppableThread is expected to make provisions for a clean shutdown via this method. The techniques used to implement this method may vary based upon the specifics of the thread. 2) If that fails it interrupts the thread. 3) If the thread does not respond to the interrupt, it invalidates the environment. All Stoppable threads are expected to catch an interrupt, clean up and then exit. The cleanup may involve invalidation of the environment, if the thread is not in a position to handle the interrupt cleanly. If the method has to resort to step 3, it means that thread and other resources may not have been freed and it would be best to exit and restart the process itself to ensure they are freed. In this case an EnvironmentWedgedException is used to invalidate the env, and the EWE will be thrown when the app calls Environment.close.

Parameters:

logger - the logger on which to log messages

initiateSoftShutdown

protected int initiateSoftShutdown()

Threads that use shutdownThread() must define this method. It's invoked by shutdownThread as an attempt at a soft shutdown. This method makes provisions for this thread to exit on its own. The technique used to make the thread exit can vary based upon the nature of the service being provided by the thread. For example, the thread may be known to poll some shutdown flag on a periodic basis, or it may detect that a channel that it waits on has been closed by this method.

Returns:

the amount of time in ms that the shutdownThread method will wait for the thread to exit. A -ve value means that the method will not wait. A zero value means it will wait indefinitely.

getTotalCpuTime

public long getTotalCpuTime()

Returns the total cpu time associated with the thread, after the thread has been shutdown.

getTotalUserTime

public long getTotalUserTime()

Returns the total cpu time associated with the thread, after the thread has been shutdown.