de.fu_berlin.ties.util
Class TaskRunner

java.lang.Object
  extended byde.fu_berlin.ties.util.TaskRunner
All Implemented Interfaces:
Closeable

public class TaskRunner
extends Object
implements Closeable

Asynchronously executes any number of Runnable tasks. Internally manages a pool of worker threads that are invoked to asychronously execute tasks as requested. The number of worker threads is updated on demand so every task is executed without delay.

Usually it should be sufficient to invoke tasks through the static invokeDefault(java.lang.Runnable, java.lang.String) methods; in most cases there should be no reason to create instances of this class. To avoid the creation of unnecessary instances, it is highly recommended to register your interest (registerInterest()) in the default task runner prior to using it and to deregister (deregisterInterest()) when you no longer need it. A good idea is to do this at the begin and end of your main method. You should register in a finally block and you must not forget to deregister, otherwise your program might run forever (because the worker threads continue waiting for tasks even after all other threads have terminated).

When creating your own runner, you must finally call close() to release each task runner you have created, or your program might run forever.

Version:
$Revision: 1.2 $, $Date: 2004/03/04 17:50:00 $, $Author: siefkes $
Author:
Christian Siefkes

Field Summary
static String DEFAULT_NAME
          The base name of worker threads used by the default instance.
 
Constructor Summary
TaskRunner(String baseThreadName)
          Creates a new instance, using the default priority (Thread.NORM_PRIORITY) for threads.
TaskRunner(String baseThreadName, int defaultPrio)
          Creates a new instance.
 
Method Summary
 void close()
          Closes this task runner.
static void deregisterInterest()
          Deregisters interest to use the default runner.
protected  void finalize()
          Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
 String getBaseName()
          Returns the base name of worker threads.
 int getDefaultPriority()
          Returns the default priority to use for threads.
 void invoke(Runnable task, String taskName)
          Invokes a task to be executed asynchronously.
 void invoke(Runnable task, String taskName, int priority)
          Invokes a task to be executed asynchronously.
static void invokeDefault(Runnable task, String taskName)
          Invokes a task to be executed asynchronously, using the default task runner.
static void invokeDefault(Runnable task, String taskName, int priority)
          Invokes a task to be executed asynchronously using the default task runner.
 boolean isClosed()
          Returns whether this task runner has been closed.
static void registerInterest()
          Registers interest to use the default runner.
 String toString()
          Returns a string representation of this object.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_NAME

public static final String DEFAULT_NAME
The base name of worker threads used by the default instance.

See Also:
Constant Field Values
Constructor Detail

TaskRunner

public TaskRunner(String baseThreadName)
Creates a new instance, using the default priority (Thread.NORM_PRIORITY) for threads.

Parameters:
baseThreadName - the base name of worker threads -- the actual names are formed by appending the next available number

TaskRunner

public TaskRunner(String baseThreadName,
                  int defaultPrio)
           throws IllegalArgumentException
Creates a new instance.

Parameters:
baseThreadName - the base name of worker threads -- the actual names are formed by appending the next available number
defaultPrio - the priority to use for threads; should be in the range of Thread.MIN_PRIORITY to Thread.MAX_PRIORITY
Throws:
IllegalArgumentException - if the priority is not in the range Thread.MIN_PRIORITY to Thread.MAX_PRIORITY
Method Detail

deregisterInterest

public static void deregisterInterest()
Deregisters interest to use the default runner. You must have called registerInterest() prior to calling this method. You should calls this method in a finally block to ensure it is always executed.


invokeDefault

public static void invokeDefault(Runnable task,
                                 String taskName)
Invokes a task to be executed asynchronously, using the default task runner. This method returns immediately; the given task is executed in another thread. The task is executed with the default priority (Thread.NORM_PRIORITY).

Parameters:
task - the Runnable to be executed asynchronously
taskName - a name or short description of the new task -- used for debugging purposes

invokeDefault

public static void invokeDefault(Runnable task,
                                 String taskName,
                                 int priority)
                          throws IllegalArgumentException
Invokes a task to be executed asynchronously using the default task runner. This method returns immediately; the given task is executed in another thread.

Parameters:
task - the Runnable to be executed asynchronously
taskName - a name or short description of the new task -- used for debugging purposes
priority - the priority to use for the thread executing the task; should be in the range of Thread.MIN_PRIORITY to Thread.MAX_PRIORITY
Throws:
IllegalArgumentException - if the priority is not in the range Thread.MIN_PRIORITY to Thread.MAX_PRIORITY

registerInterest

public static void registerInterest()
Registers interest to use the default runner. You must deregisterInterest() some time after calling this method, otherwise your program will not terminate regularly.


close

public final void close()
Closes this task runner. All thread will be terminated after executing their current tasks, so no tasks will be lost. You must call this method to release each task runner you created, or your program might run forever (because the worker threads continue waiting for tasks even after all other threads have terminated). You must not call invoke(Runnable, String) after calling this method.

Specified by:
close in interface Closeable

finalize

protected final void finalize()
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. Delegates to close() to terminate all worker threads if not yet done. You should not rely on this method but always call close() yourself.


getBaseName

public final String getBaseName()
Returns the base name of worker threads. The actual names of worker threads are formed by appending the next available number to this name (baseName + 1, baseName + 2 etc.)

Returns:
the base name

getDefaultPriority

public final int getDefaultPriority()
Returns the default priority to use for threads.

Returns:
the priority

invoke

public final void invoke(Runnable task,
                         String taskName)
Invokes a task to be executed asynchronously. This method returns immediately; the given task is executed in another thread. The task is executed with the default priority of this task runner (getDefaultPriority()).

Parameters:
task - the Runnable to be executed asynchronously
taskName - a name or short description of the new task -- used for debugging purposes

invoke

public final void invoke(Runnable task,
                         String taskName,
                         int priority)
                  throws IllegalArgumentException
Invokes a task to be executed asynchronously. This method returns immediately; the given task is executed in another thread.

Parameters:
task - the Runnable to be executed asynchronously
taskName - a name or short description of the new task -- used for debugging purposes
priority - the priority to use for the thread executing the task; should be in the range of Thread.MIN_PRIORITY to Thread.MAX_PRIORITY
Throws:
IllegalArgumentException - if the priority is not in the range Thread.MIN_PRIORITY to Thread.MAX_PRIORITY

isClosed

public final boolean isClosed()
Returns whether this task runner has been closed.

Returns:
true iff close() has been called on this object

toString

public String toString()
Returns a string representation of this object.

Returns:
a textual representation


Copyright © 2003-2004 Christian Siefkes. All Rights Reserved.