lava.thread
Class ThreadSerializer

java.lang.Object
  |
  +--lava.thread.ThreadSerializer

public class ThreadSerializer

extends java.lang.Object

Executes multiple threads in serial order.

Details: ThreadSerializer manages a prioritized queue of unstarted threads and Runnable objects and executes them one at a time, so that only one Thread or Runnable from the queue is ever executing at any given time. ThreadSerializer runs the thread at the head of the queue, waits for it to die, and then executes the next thread, repeating until the queue is empty. Once the queue is empty, ThreadSerializer either dies or blocks until more threads are enqueued, depending on how it is configured.

Both Threads and Runnables can be lined up in the queue. Threads are invoked using the start method; Runnables are invoked using the run method. Enqueuing Runnables is more efficient than enqueuing Threads because the serializer runs Runnables in its own thread.

Since:

1999.09.01

Version:

1999.09.07

Author:

Sharky

Constructor Summary

ThreadSerializer()
Default constructor.

Method Summary

int	countEnqueuedThreads() Counts enqueued threads.
void	enqueue(java.lang.Runnable runnable, int priority) Enqueues lightweight thread.
void	enqueue(java.lang.Thread thread, int priority) Enqueues unstarted thread.
void	finishNow() Waits for queue to empty.
void	finishSoon() Allows ThreadSerializer to die.
java.lang.Runnable	getEnqueuedThread(int pos) Returns enqueued thread.
void	resume() Resumes thread execution.
void	start() Begins executing threads.
void	stopNow() Synchronously stops thread execution.
void	stopSoon() Asynchronously stops thread execution.
void	suspendNow() Synchronously suspends thread execution.
void	suspendSoon() Asynchronously suspends thread execution.

Methods inherited from class java.lang.Object

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

Constructor Detail

ThreadSerializer

public ThreadSerializer()

Default constructor.

Method Detail

start

public void start()

Begins executing threads.

Details: This method starts this ThreadSerializer into action. The first of the enqueued threads is immediately started. If no threads are enqueued, then the first thread to be enqueued after this method returns will be immediately executed.

suspendSoon

public void suspendSoon()

Asynchronously suspends thread execution.

Details: This method instructs this ThreadSerializer to temporarily stop executing threads after the currently executing thread finishes. The method returns immediately, and the currently executing thread is allowed to continue, but no additional threads will be started until one of the resume methods has been called.

This method has no effect if this ThreadSerializer is already suspended, not yet started, or dead.

suspendNow

public void suspendNow()

Synchronously suspends thread execution.

Details: This method instructs this ThreadSerializer to temporarily stop executing threads after the currently executing thread finishes. The method does not return until the currently executing thread has finished. No additional threads will be started until one of the resume methods has been called.

This method has no effect and returns immediately if this ThreadSerializer is already suspended, not yet started, or dead.

resume

public void resume()

Resumes thread execution.

Details: This method causes this ThreadSerializer to resume executing threads, starting with the thread at the head of the queue.

This method has no effect if this ThreadSerializer is not suspended, not yet started, or dead.

stopSoon

public void stopSoon()

Asynchronously stops thread execution.

Details: This method instructs this ThreadSerializer to permanently stop executing threads after the currently executing thread finishes. The method returns immediately, and the currently executing thread is allowed to continue, but no additional threads will be allowed to run. If any unstarted threads are still in the queue, they will be purged.

This method has immediate effect if this ThreadSerializer is currently suspended and no effect if this ThreadSerializer is already stopped. If this ThreadSerializer has not yet been started, stopping it will throw an IllegalThreadStateException.

stopNow

public void stopNow()

Synchronously stops thread execution.

Details: This method instructs this ThreadSerializer to stop executing threads after the currently executing thread finishes. The method does not return until the currently executing thread has finished. No additional threads will be started after this method returns. If any unstarted threads are still in the queue, they will be purged.

This method has immediate effect if this ThreadSerializer is currently suspended and no effect if this ThreadSerializer is already stopped. If this ThreadSerializer has not yet been started, stopping it will throw an IllegalThreadStateException.

finishSoon

public void finishSoon()

Allows ThreadSerializer to die.

Details: Normally, when a ThreadSerializer runs out of threads to execute, it suspends itself until more threads are enqueued. This method tells this ThreadSerializer that it can quit as soon as the thread queue becomes empty. It will not be possible to enqueue more threads after the queue has run out.

If this ThreadSerializer is suspended, calling this method will not resume thread execution. Also, it is still possible to suspend this ThreadSerializer after this method has been called.

finishNow

public void finishNow()

Waits for queue to empty.

Details: This method performs the same action as finishSoon, but does not return until this ThreadSerializer has actually died. (This is similar to Thread.join.)

Warning: This method will never return if this ThreadSerializer is currently suspended, unless another thread resumes this ThreadSerializer.

enqueue

public void enqueue(java.lang.Thread thread,
                    int priority)

Enqueues unstarted thread.

Details: This method enqueues the given unstarted thread (thread) with the given priority (priority). The priority determines where in the queue thread is inserted, and has nothing to do with the execution priority of the thread once it is actually started. To control the thread's concurrent execution priority, use thread.setPriority.

Parameters:

thread - the unstarted thread

priority - the insertion priority

enqueue

public void enqueue(java.lang.Runnable runnable,
                    int priority)

Enqueues lightweight thread.

Details: This method enqueues the given Runnable (runnable) as a "lightweight thread" with the given priority (priority). The priority determines where in the queue runnable is inserted, and has nothing to do with the execution priority of the Runnable once it is actually started.

Parameters:

runnable - the Runnable

priority - the insertion priority

getEnqueuedThread

public java.lang.Runnable getEnqueuedThread(int pos)

Returns enqueued thread.

Details: getEnqueuedThread looks up and returned the enqueued thread whose queue position is pos. When a thread's queue position is 0, that means the thread is next in line to be executed.

Parameters:

pos - queue position

Returns:

enqueued thread

countEnqueuedThreads

public int countEnqueuedThreads()

Counts enqueued threads.

Details: countEnqueuedThreads determines the total number of threads that are currently encued but not running. The count is returned.

Returns:

count