Proposal for Threading Package

(0) Rationale

Many server-side applications run in an environment of multiple threads. In such environments, the issues of how to coordinate and communicate with the various threads are generic enough to be amenable to general purpose solutions. The proposed Threading Goodies package includes standard classes that can be used for these purposes.

(1) Scope of the Package

This proposal is to create a package of Java utility interfaces and classes that aid in coordinating and communication between multiple threads in a single Java Virtual Machine. The following interfaces define functionality that can be implemented with more than one set of behavioral characteristics:

• Notifier - A background thread that delivers published objects to the specified list of Subscribers.
• Publisher - An object that accepts subscriptions from interested Subscribers and delivers published messages (i.e. arbitrary Java objects) to all Subscribers.
• Queue - Message queue that supports multiple readers and multiple writers. Different implementations have different behavioral characteristics.
• Semaphore - A lock that can be acquired by only one thread at a time (with optional timeout on acquiring the lock).
• Subscriber - An object that expresses interest in messages transmitted by a Publisher by subscribing to that Publisher.

The following implementations of these interfaces are included:

• Alarm - A Publisher that fires timer events either continuously or as one-shot requests.
• AsynchPublisher - A Publisher that uses a Notifier for message delivery via a background thread. Multiple publishers can share the same Notifier, or use different ones.
• Counter - A Semaphore that maintains a counter, which is initialized in the constructor. Calls to acquire() will not block unless the count hits zero, so this object can be used (for example), to maintain the number of available elements in a Queue and automatically support thread coordination.
• FIFONotifier - A Notifier that guarantees to deliver notifications in the order received, even in the face of usage from multiple threads or very rapid calls from the same thread.
• FIFOQueue - A Queue that operates in a first-in/first-out manner (analogous to a LinkedList).
• LIFOQueue - A Queue that operates in a last-in/first-out manner (analogous to a Stack).
• Mutex - A Semaphore that can be locked by only one Thread at a time.
• SynchPublisher - A Publisher that uses the caller's thread for message delivery.

In addition, the following classes are also included:

• Condition - A simple condition variable that can be used (for example) as a "queue not empty" flag on a Queue implementation.
• MultiSemaphore - Utility class that supports locking and unlocking of multiple semaphores at once.
• Timer - A stopwatch class that measures elapsed time in milliseconds. A Timer instance can be started, stopped, and reset any number of times.

Most of the classes in the proposal were originally inspired by a series of articles called "Java Threads in the Real World" in JavaWorld (09/1998 - 04/1999) by Allen Holub.

(1.5) Interaction With Other Packages

Threading relies only on standard JDK 1.2 (or later) APIs for production deployment. It utilizes the JUnit unit testing framework for developing and executing unit tests, but this is of interest only to developers of the component.

No external configuration files are utilized.

(2) Initial Source of the Package

See the threading subdirectory in jakarta-commons-sandbox.

The proposed package name for the new component is org.apache.commons.threading.

(3) Required Jakarta-Commons Resources

• SVN repository - New directory threading in the jakarta-commons SVN repository. All initial committers are already committers on jakarta-commons, so no additional user setups are required.
• Mailing List - Discussions will take place on the general jakarta-commons@jakarta.apache.org mailing list. To help list subscribers identify messages of interest, it is suggested that the message subject of messages about this component be prefixed with [Threading].
• Bugzilla - New component "Threading" under the "Commons" product category, with appropriate version identifiers as needed.
• Jyve FAQ - New category "commons-threading" (when available).

(4) Initial Committers

The initial committers on the Threading component shall be Craig McClanahan.