From 4652d8b54843dbc2c26ba4b83858737a1987d442 Mon Sep 17 00:00:00 2001
From: mdb <mdb@6335cc39-0255-0410-8fd6-9bcaacd3b74c>
Date: Tue, 2 Oct 2001 22:35:26 +0000
Subject: [PATCH] Modified code to handle an exception that propagates up past
 iterate(). It still causes the thread to exit by default, but it provides a
 mechanism for overriding that behavior and it logs the exception rather than
 quietly dying.

git-svn-id: https://samskivert.googlecode.com/svn/trunk@334 6335cc39-0255-0410-8fd6-9bcaacd3b74c
---
 .../com/samskivert/util/LoopingThread.java    | 57 +++++++++++++------
 1 file changed, 39 insertions(+), 18 deletions(-)

diff --git a/projects/samskivert/src/java/com/samskivert/util/LoopingThread.java b/projects/samskivert/src/java/com/samskivert/util/LoopingThread.java
index fe4ef13c..14f3f20a 100644
--- a/projects/samskivert/src/java/com/samskivert/util/LoopingThread.java
+++ b/projects/samskivert/src/java/com/samskivert/util/LoopingThread.java
@@ -1,5 +1,5 @@
 //
-// $Id: LoopingThread.java,v 1.3 2001/08/11 22:43:29 mdb Exp $
+// $Id: LoopingThread.java,v 1.4 2001/10/02 22:35:26 mdb Exp $
 //
 // samskivert library - useful routines for java programs
 // Copyright (C) 2001 Michael Bayne
@@ -20,6 +20,8 @@
 
 package com.samskivert.util;
 
+import com.samskivert.Log;
+
 /**
  * The looping thread provides the basic functionality for a thread that
  * does its processing in a simple loop. This is characteristic of most
@@ -45,9 +47,8 @@ public class LoopingThread extends Thread
     }
 
     /**
-     * Processes the loop. Derived classes should override
-     * <code>iterate()</code> to perform whatever action needs to be
-     * performed inside the loop.
+     * Processes the loop. Derived classes should override {@link iterate}
+     * to perform whatever action needs to be performed inside the loop.
      */
     public void run ()
     {
@@ -55,7 +56,11 @@ public class LoopingThread extends Thread
             willStart();
 
             while (isRunning()) {
-                iterate();
+                try {
+                    iterate();
+                } catch (Exception e) {
+                    handleIterateFailure(e);
+                }
             }
 
         } finally {
@@ -65,8 +70,8 @@ public class LoopingThread extends Thread
 
     /**
      * Called to wake the thread up from any blocking wait that it might
-     * be in. This function should result in the thread exiting the
-     * iterate() function as soon as possible so that the running flag can
+     * be in. This function should result in the thread exiting the {@link
+     * iterate} function as soon as possible so that the running flag can
      * be checked and the thread can cleanly exit.
      */
     protected void kick ()
@@ -76,8 +81,8 @@ public class LoopingThread extends Thread
 
     /**
      * Called before the thread enters the processing loop. Any
-     * initialization that needs to be performed prior to the
-     * <code>iterate()</code> loop can be done here.
+     * initialization that needs to be performed prior to the {@link
+     * iterate} loop can be done here.
      */
     protected void willStart ()
     {
@@ -85,19 +90,35 @@ public class LoopingThread extends Thread
 
     /**
      * This is the main body of the loop. It will be called over and over
-     * again until the thread is requested to exit via a call to
-     * <code>shutdown()</code>. At minimum, a derived class must override
-     * this function and do something useful.
+     * again until the thread is requested to exit via a call to {@link
+     * shutdown}. At minimum, a derived class must override this function
+     * and do something useful.
      */
     protected void iterate ()
     {
         throw new RuntimeException("Derived class must implement iterate().");
     }
 
+    /**
+     * If an exception propagates past {@link iterate}, it will be caught
+     * and supplied to this function, which may want to do something
+     * useful with it. Presently, the exception is logged and the thread
+     * is allowed to terminate.
+     */
+    protected void handleIterateFailure (Exception e)
+    {
+        // log the exception
+        Log.warning("LoopingThread.iterate() uncaught exception.");
+        Log.logStackTrace(e);
+
+        // and shut the thread down
+        shutdown();
+    }
+
     /**
      * Called after the thread has been requested to exit. Any cleanup
-     * that should take place after the <code>iterate()</code> loop has
-     * exited can be done here.
+     * that should take place after the {@link iterate} loop has exited
+     * can be done here.
      */
     protected void didShutdown ()
     {
@@ -105,10 +126,10 @@ public class LoopingThread extends Thread
 
     /**
      * Indicates whether or not the thread should still be running. If a
-     * thread is calling this within <code>iterate()</code>, it should
-     * exit quickly and cleanly if the function returns false. It is
-     * automatically called as part of the iterate() loop, so normally a
-     * derived-class won't have to call it.
+     * thread is calling this within {@link iterate}, it should exit
+     * quickly and cleanly if the function returns false. It is
+     * automatically called as part of the {@link iterate} loop, so
+     * normally a derived-class won't have to call it.
      */
     protected synchronized boolean isRunning ()
     {