com.sleepycat.je.utilint
Class StoppableThread

java.lang.Object
  extended by java.lang.Thread
      extended by com.sleepycat.je.utilint.StoppableThread
All Implemented Interfaces:
ExceptionListenerUser, Runnable
Direct Known Subclasses:
ElectionAgentThread, FeederManager, LogFileFeeder, Replica.ReplayThread, RepNode, ServiceDispatcher

public abstract class StoppableThread
extends Thread
implements ExceptionListenerUser

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
protected  EnvironmentImpl envImpl
           
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
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
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.
protected  int initiateSoftShutdown()
          Threads that use shutdownThread() must define this method.
 boolean isShutdown()
           
 void saveShutdownException(Exception shutdownException)
           
 void setExceptionListener(ExceptionListener exceptionListener)
          Set every time a new exception listener is registered.
protected  boolean shutdownDone()
          Shutdown methods should only be executed once.
 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()

setExceptionListener

public void setExceptionListener(ExceptionListener exceptionListener)
Set every time a new exception listener is registered.

Specified by:
setExceptionListener in interface ExceptionListenerUser

shutdownDone

protected boolean shutdownDone()
Shutdown methods should only be executed once.

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.


shutdownThread

public void shutdownThread(Logger logger)
This method is invoked from another thread of control to shutdown this thread. It first tries a "soft" shutdown by invoking initiateSoftShutdown(). If the thread does not exit on its own in waitMs the thread is interrupted. waitMs is determined by the technique used for the soft shutdown. For example, if the thread polls on a periodic basis, it could span one or more polling periods. All Stoppable threads are expected to catch an interrupt, clean up and then exit.

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.



Copyright (c) 2004-2012 Oracle. All rights reserved.