Widening, make _running volatile instead of synchronizing on the thread.

git-svn-id: https://samskivert.googlecode.com/svn/trunk@2524 6335cc39-0255-0410-8fd6-9bcaacd3b74c

src/java/com/samskivert/util/LoopingThread.java

@@ -23,10 +23,9 @@ package com.samskivert.util;
 import static com.samskivert.Log.log;
 
 /**
- * The looping thread provides the basic functionality for a thread that
+ * The looping thread provides the basic functionality for a thread that does its processing in a
- * does its processing in a simple loop. This is characteristic of most
+ * simple loop. This is characteristic of most event processing threads that pull an event off of a
- * event processing threads that pull an event off of a queue and process
+ * queue and process it each time through the loop.
- * it each time through the loop.
  */
 public class LoopingThread extends Thread
 {
@@ -46,25 +45,23 @@ public class LoopingThread extends Thread
     }
 
     /**
-     * Requests that this thread shut itself down. The running flag will
+     * Requests that this thread shut itself down. The running flag will be cleared and if this
-     * be cleared and if this function is being called by an external
+     * function is being called by an external thread, the derived-class-specific kick function
-     * thread, the derived-class-specific kick function will be called to
+     * will be called to awake the thread from any slumber it might be in.
-     * awake the thread from any slumber it might be in.
      */
-    public synchronized void shutdown ()
+    public void shutdown ()
     {
         _running = false;
 
-        // only kick the thread if it's not requesting it's own shutdown
+        // only kick the thread if it's not requesting its own shutdown
         if (this != Thread.currentThread()) {
             kick();
         }
     }
 
     /**
-     * Processes the loop. Derived classes should override {@link
+     * Processes the loop. Derived classes should override {@link #iterate} to perform whatever
-     * #iterate} to perform whatever action needs to be performed inside
+     * action needs to be performed inside the loop.
-     * the loop.
      */
     @Override
     public void run ()
@@ -84,29 +81,27 @@ public class LoopingThread extends Thread
             log.warning("Looping thread terminated with exception.", "thread", this, t);
 
         } finally {
-            // Running needs to be false even if this exited due to a Throwable from iterate
+            // running needs to be false even if this exited due to a Throwable from iterate
             _running = false;
             didShutdown();
         }
     }
 
     /**
-     * Indicates whether or not the thread should still be running. If a
+     * Indicates whether or not the thread should still be running. If a thread is calling this
-     * thread is calling this within {@link #iterate}, it should exit
+     * within {@link #iterate}, it should exit quickly and cleanly if the function returns
-     * quickly and cleanly if the function returns false. It is
+     * false. It is automatically called as part of the {@link #iterate} loop, so normally a
-     * automatically called as part of the {@link #iterate} loop, so
+     * derived-class won't have to call it.
-     * normally a derived-class won't have to call it.
      */
-    public synchronized boolean isRunning ()
+    public boolean isRunning ()
     {
         return _running;
     }
 
     /**
-     * Called to wake the thread up from any blocking wait that it might
+     * Called to wake the thread up from any blocking wait that it might be in. This function
-     * be in. This function should result in the thread exiting the {@link
+     * should result in the thread exiting the {@link #iterate} function as soon as possible so
-     * #iterate} function as soon as possible so that the running flag can
+     * that the running flag can be checked and the thread can cleanly exit.
-     * be checked and the thread can cleanly exit.
      */
     protected void kick ()
     {
@@ -114,19 +109,17 @@ public class LoopingThread extends Thread
     }
 
     /**
-     * Called before the thread enters the processing loop. Any
+     * Called before the thread enters the processing loop. Any initialization that needs to be
-     * initialization that needs to be performed prior to the {@link
+     * performed prior to the {@link #iterate} loop can be done here.
-     * #iterate} loop can be done here.
      */
     protected void willStart ()
     {
     }
 
     /**
-     * This is the main body of the loop. It will be called over and over
+     * This is the main body of the loop. It will be called over and over again until the thread is
-     * again until the thread is requested to exit via a call to {@link
+     * requested to exit via a call to {@link #shutdown}. At minimum, a derived class must override
-     * #shutdown}. At minimum, a derived class must override this function
+     * this function and do something useful.
-     * and do something useful.
      */
     protected void iterate ()
     {
@@ -134,10 +127,9 @@ public class LoopingThread extends Thread
     }
 
     /**
-     * If an exception propagates past {@link #iterate}, it will be caught
+     * If an exception propagates past {@link #iterate}, it will be caught and supplied to this
-     * and supplied to this function, which may want to do something
+     * function, which may want to do something useful with it. Presently, the exception is logged
-     * useful with it. Presently, the exception is logged and the thread
+     * and the thread is allowed to terminate.
-     * is allowed to terminate.
      */
     protected void handleIterateFailure (Exception e)
     {
@@ -149,13 +141,12 @@ public class LoopingThread extends Thread
     }
 
     /**
-     * Called after the thread has been requested to exit. Any cleanup
+     * Called after the thread has been requested to exit. Any cleanup that should take place after
-     * that should take place after the {@link #iterate} loop has exited
+     * the {@link #iterate} loop has exited can be done here.
-     * can be done here.
      */
     protected void didShutdown ()
     {
     }
 
-    protected boolean _running = true;
+    protected volatile boolean _running = true;
 }