Package EDU.oswego.cs.dl.util.concurrent

Overview of package util.concurrent Release 1.3.2.

by Doug Lea

This package provides standardized, efficient versions of utility classes commonly encountered in concurrent Java programming.

Interface Summary

Barrier Barriers serve as synchronization points for groups of threads that must occasionally wait for each other.
BoundedChannel A channel that is known to have a capacity, signifying that put operations may block when the capacity is reached.
Callable Interface for runnable actions that bear results and/or throw Exceptions.
Channel Main interface for buffers, queues, pipes, conduits, etc.
Executor Interface for objects that execute Runnables, as well as various objects that can be wrapped as Runnables.
ObservableSync.SyncObserver Interface for objects that observe ObservableSyncs.
PooledExecutor.BlockedExecutionHandler Class for actions to take when execute() blocks.
Puttable This interface exists to enable stricter type checking for channels.
ReadWriteLock ReadWriteLocks maintain a pair of associated locks.
Rendezvous.RendezvousFunction Interface for functions run at rendezvous points
Sync Main interface for locks, gates, and conditions.
Takable This interface exists to enable stricter type checking for channels.
ThreadFactory Interface describing any class that can generate new Thread objects.

Class Summary

BoundedBuffer Efficient array-based bounded buffer class.
BoundedLinkedQueue A bounded variant of LinkedQueue class.
BoundedPriorityQueue A heap-based priority queue, using semaphores for concurrency control.
BrokenBarrierException Thrown by Barrier upon interruption of participant threads
ClockDaemon A general-purpose time-based daemon, vaguely similar in functionality to common system-level utilities such as at (and the associated crond) in Unix.
ClockDaemon.RunLoop The runloop is isolated in its own Runnable class just so that the main class need not implement Runnable, which would allow others to directly invoke run, which is not supported.
ClockDaemon.TaskNode
ConcurrentHashMap A version of Hashtable supporting concurrency for both retrievals and updates:
ConcurrentHashMap.Entry ConcurrentHashMap collision list entry.
ConcurrentHashMap.HashIterator
ConcurrentHashMap.KeyIterator
ConcurrentHashMap.Segment Bookkeeping for each concurrency control segment.
ConcurrentHashMap.ValueIterator
ConcurrentReaderHashMap A version of Hashtable that supports mostly-concurrent reading, but exclusive writing.
ConcurrentReaderHashMap.BarrierLockA Serializable class for barrier lock *
ConcurrentReaderHashMap.Entry ConcurrentReaderHashMap collision list entry.
ConcurrentReaderHashMap.HashIterator
ConcurrentReaderHashMap.KeyIterator
ConcurrentReaderHashMap.ValueIterator
CondVar This class is designed for fans of POSIX pthreads programming.
CopyOnWriteArrayList This class implements a variant of java.util.ArrayList in which all mutative operations (add, set, and so on) are implemented by making a fresh copy of the underlying array.
CopyOnWriteArrayList.COWIterator
CopyOnWriteArrayList.COWSubList
CopyOnWriteArrayList.COWSubList.COWSubListIterator
CopyOnWriteArraySet This class implements a java.util.Set that uses a CopyOnWriteArrayList for all of its operations.
CountDown A CountDown can serve as a simple one-shot barrier.
CyclicBarrier A cyclic barrier is a reasonable choice for a barrier in contexts involving a fixed sized group of threads that must occasionally wait for each other.
DefaultChannelCapacity A utility class to set the default capacity of BoundedChannel implementations that otherwise require a capacity argument
DirectExecutor An implementation of Executor that invokes the run method of the supplied command and then returns.
FIFOReadWriteLock This class implements a policy for reader/writer locks in which threads contend in a First-in/First-out manner for access (modulo the limitations of FIFOSemaphore, which is used for queuing).
FIFOReadWriteLock.ReaderSync
FIFOReadWriteLock.WriterSync
FIFOSemaphore A First-in/First-out implementation of a Semaphore.
FIFOSemaphore.FIFOWaitQueue Simple linked list queue used in FIFOSemaphore.
FJTask Abstract base class for Fork/Join Tasks.
FJTask.Par A new Par, when executed, runs the tasks provided in the constructor in parallel using coInvoke(tasks).
FJTask.Par2 A new Par(task1, task2), when executed, runs task1 and task2 in parallel using coInvoke(task1, task2).
FJTask.Seq A new Seq, when executed, invokes each task provided in the constructor, in order.
FJTask.Seq2 A new Seq2(task1, task2), when executed, invokes task1 and then task2, in order.
FJTask.Wrap A FJTask that holds a Runnable r, and calls r.run when executed.
FJTaskRunner Specialized Thread subclass for running FJTasks.
FJTaskRunner.VolatileTaskRef An object holding a single volatile reference to a FJTask.
FJTaskRunnerGroup A stripped down analog of a ThreadGroup used for establishing and managing FJTaskRunner threads.
FJTaskRunnerGroup.InvokableFJTask Wrap wait/notify mechanics around a task so that invoke() can wait it out
FutureResult A class maintaining a single reference variable serving as the result of an operation.
Heap A heap-based priority queue, without any concurrency control (i.e., no blocking on empty/full states).
Latch A latch is a boolean condition that is set at most once, ever.
LayeredSync A class that can be used to compose Syncs.
LinkedNodeA standard linked list node used in various queue classes *
LinkedQueue A linked list based channel implementation.
LockedExecutor An implementation of Executor that invokes the run method of the supplied command within a synchronization lock and then returns.
Mutex A simple non-reentrant mutual exclusion lock.
NullSync A No-Op implementation of Sync.
ObservableSync The ObservableSync class performs no synchronization itself, but invokes event-style messages to other observer objects upon invocation of Sync methods.
PooledExecutor A tunable, extensible thread pool class.
PooledExecutor.AbortWhenBlockedClass defining Abort action.
PooledExecutor.DiscardOldestWhenBlocked Class defining DiscardOldest action.
PooledExecutor.DiscardWhenBlockedClass defining Discard action.
PooledExecutor.RunWhenBlockedClass defining Run action.
PooledExecutor.WaitWhenBlockedClass defining Wait action.
PooledExecutor.Worker Class defining the basic run loop for pooled threads.
PrioritySemaphore A Semaphore that grants requests to threads with higher Thread priority rather than lower priority when there is contention.
PrioritySemaphore.PriorityWaitQueue
PropertyChangeMulticaster This class is interoperable with java.beans.PropertyChangeSupport, but relies on a streamlined copy-on-write scheme similar to that used in CopyOnWriteArrayList.
QueuedExecutor An implementation of Executor that queues incoming requests until they can be processed by a single background thread.
QueuedExecutor.RunLoop The runloop is isolated in its own Runnable class just so that the main class need not implement Runnable, which would allow others to directly invoke run, which would never make sense here.
QueuedSemaphore Abstract base class for semaphores relying on queued wait nodes.
QueuedSemaphore.WaitQueue Base class for internal queue classes for semaphores, etc.
QueuedSemaphore.WaitQueue.WaitNode
ReaderPreferenceReadWriteLock A ReadWriteLock that prefers waiting readers over waiting writers when there is contention.
ReentrantLock A lock with the same semantics as builtin Java synchronized locks: Once a thread has a lock, it can re-obtain it any number of times without blocking.
ReentrantWriterPreferenceReadWriteLock A writer-preference ReadWriteLock that allows both readers and writers to reacquire read or write locks in the style of a ReentrantLock.
Rendezvous A rendezvous is a barrier that:
  • Unlike a CyclicBarrier, is not restricted to use with fixed-sized groups of threads.
Rendezvous.Rotator The default rendezvous function.
Semaphore Base class for counting semaphores.
SemaphoreControlledChannel Abstract class for channels that use Semaphores to control puts and takes.
Slot A one-slot buffer, using semaphores to control access.
SyncCollection SyncCollections wrap Sync-based control around java.util.Collections.
SyncCollection.SyncCollectionIterator
SynchronizedBoolean A class useful for offloading synch for boolean instance variables.
SynchronizedByte A class useful for offloading synch for byte instance variables.
SynchronizedChar A class useful for offloading synch for char instance variables.
SynchronizedDouble A class useful for offloading synch for double instance variables.
SynchronizedFloat A class useful for offloading synch for float instance variables.
SynchronizedInt A class useful for offloading synch for int instance variables.
SynchronizedLong A class useful for offloading synch for long instance variables.
SynchronizedRef A simple class maintaining a single reference variable that is always accessed and updated under synchronization.
SynchronizedShort A class useful for offloading synch for short instance variables.
SynchronizedVariable Base class for simple, small classes maintaining single values that are always accessed and updated under synchronization.
SynchronousChannel A rendezvous channel, similar to those used in CSP and Ada.
SynchronousChannel.Queue Simple FIFO queue class to hold waiting puts/takes.
SyncList SyncLists wrap Sync-based control around java.util.Lists.
SyncList.SyncCollectionListIterator
SyncMap SyncMaps wrap Sync-based control around java.util.Maps.
SyncSet SyncSets wrap Sync-based control around java.util.Sets.
SyncSortedMap SyncSortedMaps wrap Sync-based control around java.util.SortedMaps.
SyncSortedSet SyncSortedSets wrap Sync-based control around java.util.SortedSets.
ThreadedExecutor An implementation of Executor that creates a new Thread that invokes the run method of the supplied command.
ThreadFactoryUser Base class for Executors and related classes that rely on thread factories.
ThreadFactoryUser.DefaultThreadFactory
TimedCallable TimedCallable runs a Callable function for a given length of time.
TimeoutException Thrown by synchronization classes that report timeouts via exceptions.
TimeoutSync A TimeoutSync is an adaptor class that transforms all calls to acquire to instead invoke attempt with a predetermined timeout value.
VetoableChangeMulticaster This class is interoperable with java.beans.VetoableChangeSupport, but relies on a streamlined copy-on-write scheme similar to that used in CopyOnWriteArrayList.
WaitableBoolean A class useful for offloading synch for boolean instance variables.
WaitableByte A class useful for offloading waiting and signalling operations on single byte variables.
WaitableChar A class useful for offloading waiting and signalling operations on single char variables.
WaitableDouble A class useful for offloading waiting and signalling operations on single double variables.
WaitableFloat A class useful for offloading waiting and signalling operations on single float variables.
WaitableInt A class useful for offloading waiting and signalling operations on single int variables.
WaitableLong A class useful for offloading waiting and signalling operations on single long variables.
WaitableRef A class useful for offloading synch for Object reference instance variables.
WaitableShort A class useful for offloading waiting and signalling operations on single short variables.
WaiterPreferenceSemaphore An implementation of counting Semaphores that enforces enough fairness for applications that need to avoid indefinite overtaking without necessarily requiring FIFO ordered access.
WaitFreeQueue A wait-free linked list based queue implementation.
WaitFreeQueue.NodeList nodes for Queue *
WriterPreferenceReadWriteLock A ReadWriteLock that prefers waiting writers over waiting readers when there is contention.
WriterPreferenceReadWriteLock.ReaderLock
WriterPreferenceReadWriteLock.Signaller Reader and Writer requests are maintained in two different wait sets, by two different objects.
WriterPreferenceReadWriteLock.WriterLock

Overview of package util.concurrent Release 1.3.2.

by
Doug Lea

This package provides standardized, efficient versions of utility classes commonly encountered in concurrent Java programming. This code consists of implementations of ideas that have been around for ages, and is merely intended to save you the trouble of coding them. Discussions of the rationale and applications of several of these classes can be found in the second edition of Concurrent Programming in Java. There are also pdf slides providing an overview of the package. See also JSR 166 that will define a similar package for an upcoming JDK release.

The package mainly consists of implementations of a few interfaces:

Plus some utilities and frameworks that build upon these.

If you arrived at page
http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html
following links from your local documentation, please check the version number and get an update if you are running an outdated version.

Installation

This package, currently declared as
EDU.oswego.cs.dl.util.concurrent
is available in (tar.gz format) or (zip format).

It is currently distributed in source form only. To build it, use a Java 1.2+ compiler to:

  javac -d [SOMEWHERE IN YOUR CLASSPATH] *.java

The classes in the misc directory can be built the same way.

To use it, add to java files:

  import EDU.oswego.cs.dl.util.concurrent.*

You can also create a jar or zip file of the compiled classes and add them to your classpath.

All documentation except for this file was produced by (JDK1.2) javadoc, which places some index and summary files outside the current directory. This can cause some broken links on unpacked versions. You can avoid this, and integrate with your local javadoc-produced documentation by running:

  javadoc -public -d [BASE OF SOME JAVADOC PATH] *.java

Contents

Sync
acquireattempt(msecs)release

Implementations

Semaphore
WaiterPreferenceSemaphore
FIFOSemaphore
PrioritySemaphore
Mutex
ReentrantLock
Latch
CountDown
nth

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
TimeoutSync
LayeredSync
ObservableSync

Related Classes

CondVar
TimeoutException

ReadWriteLock

Implementations

WriterPreferenceReadWriteLock
ReentrantWriterPreferenceReadWriteLock
ReaderPreferenceReadWriteLock
FIFOReadWriteLock

Barrier

Implementations

CyclicBarrier
Rendezvous

Related Classes

BrokenBarrierException

Channel
puttakeofferpollPuttableTakableBoundedChannel

Implementations

LinkedQueue
BoundedLinkedQueue
BoundedBuffer
Slot
SynchronousChannel
BoundedPriorityQueue
WaitFreeQueue

Related Classes

DefaultChannelCapacity

Executor
execute

Implementations

DirectExecutor
LockedExecutor
ThreadedExecutor
QueuedExecutor
PooledExecutor

Related classes

Callable
FutureResult
ThreadFactory
ThreadFactoryUser
ClockDaemon
TimedCallable

Fork/Join Tasks
FJTask
FJTaskRunnerGroup
FJTaskRunner
Demos and examples
the design and performance of this framework

Collections
ConcurrentReaderHashMap
ConcurrentHashMap
CopyOnWriteArrayList
CopyOnWriteArraySet
SyncCollection
SyncSet
SyncSortedSet
SyncList
SyncMap
SyncSortedMap
Related classes
PropertyChangeMulticaster
VetoableChangeMulticaster

SynchronizedVariable

Miscellany
misc

Notes

Some Questions and Answers about Design and Implementation

Thread.currentThread().interrupt()

  void quietlyAcquire(Sync sync) {
boolean wasInterrupted = Thread.interrupted(); // record and clear
for (;;) {
try {
sync.acquire();   // or any other method throwing InterruptedException
break;
}
catch (InterruptedException ex) { // re-interrupted; try again
wasInterrupted = true;
}
}
if (wasInterrupted) {              // re-establish interrupted state
Thread.currentThread().interrupt();
}
}

CPJ supplement page on cancellation

synchronizedSynchronizationTimersynchronized

volatile

protected

Serializable

xsynchronized(x) { ... }
synchronized(x)

EDUedu

Sample Java Coding Standard

Sources

History

  • 7Jan 1999 Version 1.2
  • 13Jan1999 version 1.2.1
  • 17Jan1999 version 1.2.2:
  • 25Mar1999 version 1.2.3
  • 21may1999 version 1.2.4
  • 23oct1999 version 1.2.5
  • 29dec1999 version 1.2.6
  • 12jan2001 version 1.3.0
  • 2dec2001 Version 1.3.1
  • 12dec2002 Version 1.3.2
  • Coming attractions