Refactored the Invoker into a generic class which PresentsServer extends

to do its custom fiddly business. git-svn-id: https://samskivert.googlecode.com/svn/trunk@1454 6335cc39-0255-0410-8fd6-9bcaacd3b74c
2004-06-29 03:14:22 +00:00
parent 4f32abb4a5
commit eb6de7d075
1 changed files with 189 additions and 0 deletions
@@ -0,0 +1,189 @@
+//
+// $Id: Invoker.java,v 1.1 2004/06/29 03:14:22 mdb Exp $
+
+package com.samskivert.util;
+
+import java.util.HashMap;
+import java.util.Iterator;
+
+import com.samskivert.Log;
+
+/**
+ * The invoker is used to invoke self-contained units of code on an
+ * invoking thread. Each invoker is associated with its own thread and
+ * that thread is used to invoke all of the units posted to that invoker
+ * in the order in which they were posted. The invoker also provides a
+ * convenient mechanism for processing the result of an invocation back on
+ * the main thread.
+ *
+ * <p> The invoker is a useful tool for services that need to block and
+ * therefore cannot be run on the main thread. For example, an interactive
+ * application might provide an invoker on which to run database queries.
+ *
+ * <p> Bear in mind that each invoker instance runs units on its own
+ * thread and care must be taken to ensure that code running on separate
+ * invokers properly synchronizes access to shared information. Where
+ * possible, complete isolation of the services provided by a particular
+ * invoker is desirable.
+ */
+public class Invoker extends LoopingThread
+{
+    /** An interface by which the invoker communicates back to the entity
+     * that manages the main thread. */
+    public static interface ResultReceiver
+    {
+        /** Posts an unit that should be executed on the main thread. */
+        public void postUnit (Runnable unit);
+    }
+
+    /**
+     * The unit encapsulates a unit of executable code that will be run on
+     * the invoker thread. It also provides facilities for additional code
+     * to be run on the main thread once the primary code has completed on
+     * the invoker thread.
+     */
+    public static abstract class Unit implements Runnable
+    {
+        /** The default constructor. */
+        public Unit () {}
+
+        /** Creates an invoker unit which will report the supplied name in
+         * {@link #toString}. */
+        public Unit (String name)
+        {
+            _name = name;
+        }
+
+        /**
+         * This method is called on the invoker thread and should be used
+         * to perform the primary function of the unit. It can return true
+         * to cause the <code>handleResult</code> method to be
+         * subsequently invoked on the dobjmgr thread (generally to allow
+         * the results of the invocation to be acted upon back in the
+         * context of the regular world) or false to indicate that no
+         * further processing should be performed.
+         *
+         * @return true if the <code>handleResult</code> method should be
+         * invoked on the main thread, false if not.
+         */
+        public abstract boolean invoke ();
+
+        /**
+         * Invocation unit implementations can implement this function to
+         * perform any post-unit-invocation processing back on the main
+         * thread. It will be invoked if <code>invoke</code> returns true.
+         */
+        public void handleResult ()
+        {
+            // do nothing by default
+        }
+
+        // we want to be a runnable to make the receiver interface simple,
+        // but we'd like for invocation unit implementations to be able to
+        // put their result handling code into an aptly named method
+        public void run ()
+        {
+            handleResult();
+        }
+
+        /** Returns the name of this invoker. */
+        public String toString ()
+        {
+            return _name;
+        }
+
+        protected String _name = "Unknown";
+    }
+
+    /**
+     * Creates an invoker that will post results to the supplied result
+     * receiver.
+     */
+    public Invoker (String name, ResultReceiver receiver)
+    {
+        super(name);
+        _receiver = receiver;
+    }
+
+    /**
+     * Posts a unit to this invoker for subsequent invocation on the
+     * invoker's thread.
+     */
+    public void postUnit (Unit unit)
+    {
+        // simply append it to the queue
+        _queue.append(unit);
+    }
+
+    // documentation inherited
+    public void iterate ()
+    {
+        // pop the next item off of the queue
+        Unit unit = (Unit) _queue.get();
+
+        long start;
+        if (PERF_TRACK) {
+            start = System.currentTimeMillis();
+            _unitsRun++;
+        }
+
+        try {
+            if (unit.invoke()) {
+                // if it returned true, we post it to the receiver thread
+                // to invoke the result processing
+                _receiver.postUnit(unit);
+            }
+
+            // track some performance metrics
+            if (PERF_TRACK) {
+                long duration = System.currentTimeMillis() - start;
+                Object key = unit.getClass();
+                Histogram histo = (Histogram)_tracker.get(key);
+                if (histo == null) {
+                    // track in buckets of 50ms up to 500ms
+                    _tracker.put(key, histo = new Histogram(0, 50, 10));
+                }
+                histo.addValue((int)duration);
+
+                // report long runners
+                if (duration > 500L) {
+                    Log.warning("Invoker unit ran for '" + duration + "ms: " +
+                                unit + "' (" + key + ").");
+                }
+            }
+
+        } catch (Exception e) {
+            Log.warning("Invocation unit failed [unit=" + unit + "].");
+            Log.logStackTrace(e);
+        }
+    }
+
+    /**
+     * Shuts down the invoker thread by queueing up a unit that will cause
+     * the thread to exit after all currently queued units are processed.
+     */
+    public void shutdown ()
+    {
+        _queue.append(new Unit() {
+            public boolean invoke () {
+                _running = false;
+                return false;
+            }
+        });
+    }
+
+    /** The invoker's queue of units to be executed. */
+    protected Queue _queue = new Queue();
+
+    /** The result receiver with which we're working. */
+    protected ResultReceiver _receiver;
+
+    /** Tracks the counts of invocations by unit's class. */
+    protected HashMap _tracker = new HashMap();
+
+    /** The total number of invoker units run since the last report. */
+    protected int _unitsRun;
+
+    /** Whether or not to track invoker unit performance. */
+    protected static final boolean PERF_TRACK = true;
+}