com.samskivert.util
Class Invoker

java.lang.Object
  java.lang.Thread
      com.samskivert.util.LoopingThread
          com.samskivert.util.Invoker

All Implemented Interfaces:

RunQueue, Runnable

public class Invoker
extends LoopingThread
implements RunQueue

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.

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.

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.

Nested Class Summary

static class	Invoker.Unit The unit encapsulates a unit of executable code that will be run on the invoker thread.
protected static class	Invoker.UnitProfile Used to track profile information on invoked units.

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

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

protected static long	_defaultLongThreshold The duration of time after which we consider a unit to be delinquent and log a warning.
protected Queue<Invoker.Unit>	_queue The invoker's queue of units to be executed.
protected RunQueue	_receiver The result receiver with which we're working.
protected HashMap<Object,Invoker.UnitProfile>	_tracker Tracks the counts of invocations by unit's class.
protected int	_unitsRun The total number of invoker units run since the last report.
protected static boolean	PERF_TRACK Whether or not to track invoker unit performance.

Fields inherited from class com.samskivert.util.LoopingThread

_running

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Fields inherited from interface com.samskivert.util.RunQueue

AWT

Constructor Summary

Invoker(String name, RunQueue resultReceiver)
Creates an invoker that will post results to the supplied result receiver.

Method Summary

protected void	didInvokeUnit(Invoker.Unit unit, long start) Called before we process an invoker unit.
boolean	isDispatchThread()
void	iterate() This is the main body of the loop.
void	postRunnable(Runnable r) Post the specified Runnable to be run on the RunQueue.
void	postUnit(Invoker.Unit unit) Posts a unit to this invoker for subsequent invocation on the invoker's thread.
protected void	recordMetrics(Object key, long duration)
static void	setDefaultLongThreshold(long millis) Configures the default duration (in milliseconds) for an invoker unit to be reported as "long".
void	shutdown() Shuts down the invoker thread by queueing up a unit that will cause the thread to exit after all currently queued units are processed.
protected void	willInvokeUnit(Invoker.Unit unit, long start) Called before we process an invoker unit.

Methods inherited from class com.samskivert.util.LoopingThread

didShutdown, handleIterateFailure, isRunning, kick, run, willStart

Methods inherited from class java.lang.Thread

activeCount, checkAccess, 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, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

_queue

protected Queue<Invoker.Unit> _queue

The invoker's queue of units to be executed.

_receiver

protected RunQueue _receiver

The result receiver with which we're working.

_tracker

protected HashMap<Object,Invoker.UnitProfile> _tracker

Tracks the counts of invocations by unit's class.

_unitsRun

protected int _unitsRun

The total number of invoker units run since the last report.

_defaultLongThreshold

protected static long _defaultLongThreshold

The duration of time after which we consider a unit to be delinquent and log a warning.

PERF_TRACK

protected static final boolean PERF_TRACK

Whether or not to track invoker unit performance.

See Also:

Constant Field Values

Constructor Detail

Invoker

public Invoker(String name,
               RunQueue resultReceiver)

Creates an invoker that will post results to the supplied result receiver.

Method Detail

setDefaultLongThreshold

public static void setDefaultLongThreshold(long millis)

Configures the default duration (in milliseconds) for an invoker unit to be reported as "long". Long units will result in a warning message written to the log.

postUnit

public void postUnit(Invoker.Unit unit)

Posts a unit to this invoker for subsequent invocation on the invoker's thread.

postRunnable

public void postRunnable(Runnable r)

Description copied from interface: RunQueue

Post the specified Runnable to be run on the RunQueue.

Specified by:

postRunnable in interface RunQueue

isDispatchThread

public boolean isDispatchThread()

Specified by:

isDispatchThread in interface RunQueue

Returns:

true if the calling thread is the RunQueue dispatch thread.

iterate

public void iterate()

Description copied from class: LoopingThread

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 LoopingThread.shutdown(). At minimum, a derived class must override this function and do something useful.

Overrides:

iterate in class LoopingThread

shutdown

public void shutdown()

Shuts down the invoker thread by queueing up a unit that will cause the thread to exit after all currently queued units are processed.

Overrides:

shutdown in class LoopingThread

willInvokeUnit

protected void willInvokeUnit(Invoker.Unit unit,
                              long start)

Called before we process an invoker unit.

Parameters:

unit - the unit about to be invoked.

start - a timestamp recorded immediately before invocation if PERF_TRACK is enabled, 0L otherwise.

didInvokeUnit

protected void didInvokeUnit(Invoker.Unit unit,
                             long start)

Called before we process an invoker unit.

Parameters:

unit - the unit about to be invoked.

start - a timestamp recorded immediately before invocation if PERF_TRACK is enabled, 0L otherwise.

recordMetrics

protected void recordMetrics(Object key,
                             long duration)