Standardized, efficient utility classes commonly encountered in concurrent
programming.
For the master version of this page (more up-to-date, more info) please go
to http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html)
Overview of package util.concurrent Release 1.2.5
by Doug Lea
This package provides standardized, efficient versions of utility classes
commonly encountered in concurrent Java programming.
It mainly consists of implementations of a few interfaces:
Sync
-- locks, conditions
Channel
-- queues, buffers
Barrier
-- multi-party synchronization
SynchronizedVariable
-- atomic ints, refs etc
java.util.Collection
-- collections
Executor
-- replacements for direct use of Thread
Plus some utilities and frameworks that build upon these.
Contents
- Sync
- Interface for classes used as exclusion, resource management,
and related synchronization aids, supporting methods
acquire
, attempt(msecs)
, and
release
.
Implementations
- Semaphore
- Semaphores of various sorts. The default implementation
provides no special ordering guarantees. Subclasses that do
include:
- WaiterPreferenceSemaphore
- Provides protection against barging (infinite overtaking)
- FIFOSemaphore
- Provides first-in/first-out ordering
- PrioritySemaphore
- Prefers notifications to higher-priority threads
- Mutex
- Basic non-reentrant mutual exclusion lock
- ReentrantLock
- Java-style per-thread mutual exclusion lock
- Latch
- A condition that is acquirable forever more after the first release
- CountDown
- A condition that is acquirable forever more after the nth
release.
The following implementation classes do not themselves
perform any synchronization, but serve as adaptors, glue, and
extensibility hooks for those that do. They may also be helpful
when using Syncs in generic before/after constructions:
- NullSync
- A no-op implementation: acquire and attempt always succeed.
- TimeoutSync
- Routes all calls to acquire to use attempt with a predefined
timeout value.
- LayeredSync
- Cascades operations of two Syncs
- ObservableSync
- Issues calls to SyncObservers upon each acquire and release.
Related Classes
- CondVar
- Support for POSIX (pthreads) style condition variables
- TimeoutException
- A standardized time-out exception class
- ReadWriteLock
- Interface for pairs of locks, one for reading, and one for writing.
Implementations
- WriterPreferenceReadWriteLock
- The most useful and common policy
- ReentrantWriterPreferenceReadWriteLock
- Allows multiple lock holds as well as lock downgrading by writers.
- ReaderPreferenceReadWriteLock
- Prefers waiting readers to waiting writers.
- FIFOReadWriteLock
- Prefers either a writer or readers, depending on which one
arrived first.
- Barrier
- Synchronization points for groups of threads.
Implementations
- CyclicBarrier
- A tool to force multiple threads to synchronize at a given point
- Rendezvous
- A cyclic barrier that does not rely on there being
a predetermined number of participant threads, and allows
threads to exchange information at each barrier point.
Related Classes
- BrokenBarrierException
- A standardized exception for barrier synchronization failures
- Channel
- Interface for queues, buffers, conduits and pipes supporting
blocking
put
and take
,
as well as timeout-based offer
and poll
.
To assist efforts to use channels with somewhat
greater type safety, Channel
is defined as a subinterface of Puttable
and Takable, each defining only one side
of the channel.
Also, the BoundedChannel subinterface is used
for channels with finite capacities.
Implementations
- LinkedQueue
- An unbounded linked-list-based queue
- BoundedLinkedQueue
- A linked queue with a capacity bound
- BoundedBuffer
- An array-based bounded buffer
- Slot
- A one-slot bounded buffer. (Note that this can also
serve as a restricted form of Synchronized variable.)
- SynchronousChannel
- A zero-slot CSP/Ada-style channel in which every put must wait for a
take, and vice versa.
- BoundedPriorityQueue
- A channel based on a Heap data structure. Elements
must either be Comparable, or comparable using a supplied Comparator
- WaitFreeQueue
- An unbounded linked-list-based queue relying on atomic
commits and retries rather than wait/notify.
Related Classes
- DefaultChannelCapacity
- A utility class that makes
it easier to set default capacities for channels that have a
capacity that must otherwise be set in constructors.
- Executor
- Interface for objects that
execute
Runnable commands.
Implementations
- DirectExecutor
- An implementation that just directly runs command
in current thread.
- LockedExecutor
- An implementation that directly runs command
within a supplied Sync lock in current thread.
- ThreadedExecutor
- An implementation that runs each command
in a new thread.
- QueuedExecutor
- An implementation that queues commands for execution
by a single background thread.
- PooledExecutor
- A tunable, extensible thread pool class
Related classes
- Callable
- Interface for runnable actions that return results
- FutureResult
- Holder for results of actions that can be set by Callables.
- ThreadFactory
- Interface for objects that create Thread objects
- ThreadFactoryUser
- Convenient base for classes that use ThreadFactories.
- ClockDaemon
- A utility for executing commands at given times,
after given delays, or periodically with given cycles.
- Fork/Join Tasks
- A fast lightweight task framework built upon Java threads, and
geared for parallel computation. (See also an in-progress draft
discussing parallel
decomposition using Tasks.)
- FJTask
- Abstract Base class for tasks.
- FJTaskRunnerGroup
- Control class for running Tasks.
- FJTaskRunner
- Underlying specialized Thread subclass for running Tasks.
- Demos and examples
- A directory of sample programs that use the Task framework.
- Collections
- Implementations of java.util.Collection and related classes that
can help solve concurrency problems.
- CopyOnWriteArrayList
- A copy-on-write analog of java.util.ArrayList
- CopyOnWriteArraySet
- A java.util.Set based on CopyOnWriteArrayList.
- SyncCollection
- A wrapper class placing either Syncs or ReadWriteLocks
around java.util.Collection
- SyncSet
- A wrapper around java.util.Set
- SyncSortedSet
- A wrapper around java.util.SortedSet
- SyncList
- A wrapper around java.util.List
- SyncMap
- A wrapper around java.util.Map
- SyncSortedMap
- A wrapper around java.util.SortedMap
- Related classes
-
- PropertyChangeMulticaster
- A copy-on-write replacement for java.beans.PropertyChangeSupport
- VetoableChangeMulticaster
- A copy-on-write replacement for java.beans.VetoableChangeSupport
- SynchronizedVariable
- Simple synchronized analogs of Number and Ref classes in
java.lang. Each has a subclass that in addition to
maintaining synchronization, also provides notifications
upon value changes and supports guarded waits.
- Miscellany
- There are some classes in the
misc
directory
that might be of interest but aren't really part of this
package. They include:
- SynchronizationTimer,
that can be used to experiment with different synchronization
schemes. It requires Swing (JFC).
- An immutable Fraction class.
- Other implementations of the above interfaces that
are not valuable or stable enough to include here.
Notes
- All classes are released to the public domain and may be used for any purpose
whatsoever without permission or acknowledgment. Some of the CopyOnWriteArrayList
class is adapted from publicly available Sun JDK1.2 source code, and thus
probably falls under JDK copyright.
History
- 10Jul1998 1.0
- 11Jul1998 1.0.1: removed .class files from release, Fixed
documentation error, included Barrier interface.
- 12Jul1998 1.0.2: Fixed return value for swap; fixed documentation errors.
- 15Jul1998 1.0.3: Fixed more documentation errors; re-fixed swap;
other cosmetic improvements.
- 18Jul1998 1.0.4: Simplified some classes by removing
some alleged optimizations that do not actually help on some platforms;
improved SynchronizationTimer; added some documentation.
- 1Sep1998 version 1.1.0:
- Replace SynchronousChannel algorithm with fairer, more scalable one
- TimeoutException now extends InterruptedException
- Replace int counters with longs to avoid wrapping.
- new LayeredSync class
- new ObservableSync class
- new NullSync class
- new TimeoutSync class
- new SyncCollection classes
- new ReentrantWriterPreferenceReadWriteLock class
- peek added to Channel
- new ClockDaemon class
- Refactorings to standardize usage of thread factories
- removed reliance on ThreadGroups in PooledExecutor
- 7Jan 1999 Version 1.2
- ClockDaemon.shutdown allows immediate restart
- Callable.call throws Throwable, not Exception
- new Task, TaskRunner, TaskRunnerGroup classes
- new taskDemo subdirectory
- 13Jan1999 version 1.2.1
- Minor cleanup of Task classes
- 17Jan1999 version 1.2.2:
- Simplify Task classes; improve documentation;
add priority control; they are no longer labeled as `preliminary'.
- More sample programs in taskDemos
- Add warnings about reentrancy to RW locks
- Callable throws Exception again, but FutureResult handles Throwables
- 25Mar1999 version 1.2.3
- PooledExecutor -- allow pool to shrink when max size decreased
- Task -- add reset, array-based operations
- new PropertyChangeMulticaster, VetoableChangeMulticaster
- 21may1999 version 1.2.4
- PooledExecutor -- allow supplied Channel in constructor;
new methods createThreads(), drain()
- Task, TaskRunner, TaskRunnerGroup renamed to
FJTask, FJTaskRunner, FJTaskRunnerGroup to avoid
clashes with commonly used class name of `Task'.
- Misc documentation improvements
- WriterPreferenceReadWriteLock -- fix to notify on interrupt
- 23oct1999 1.2.5
- PooledExecutor -- add minimumPoolSize settings
- LU in taskDemo
- Minor improvements to LinkedQueue, FJTaskRunner
- Coming attractions
- End-of-lifetime of ClockDaemon! A similar class will
be included in JDK 1.3 release.
- InputTask framework.
- More concurrent data structures.
Doug Lea
Last modified: Sat Oct 23 19:47:08 EDT 1999