util/concurrent/package.html

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>Concurrency Utilities</title>
</head>

<body>

<p> Utility classes commonly useful in concurrent programming.  This
package includes a few small standardized extensible frameworks, as
well as some classes that provide useful functionality and are
otherwise tedious or difficult to implement.  Here are brief
descriptions of the main components. See also the <tt>locks</tt> and
<tt>atomic</tt> packages.

<h2>Executors</h2>

{@link java.util.concurrent.Executor} is a simple standardized
interface for defining custom thread-like subsystems, including thread
pools, asynchronous IO, and lightweight task frameworks.  Depending on
which concrete Executor class is being used, tasks may execute in a
newly created thread, an existing task-execution thread, or the thread
calling <tt>execute()</tt>, and may execute sequentially or
concurrently.  
 
<p> {@link java.util.concurrent.ExecutorService} provides a more
complete framework for executing Runnables.  An ExecutorService
manages queueing and scheduling of tasks, and allows controlled
shutdown.  The two primary implementations of ExecutorService are
{@link java.util.concurrent.ThreadPoolExecutor}, a tunable and
flexible thread pool and {@link
java.util.concurrent.ScheduledExecutor}, which adds support for
delayed and periodic task execution.  The {@link
java.util.concurrent.Executors} class provides factory methods for the
most common kinds and configurations of Executors, as well as a few
utility methods for using them.

<p> Executors may be used with threads that compute functions
returning results. A {@link java.util.concurrent.Future} returns the
results of a {@link java.util.concurrent.Callable}, the result-bearing
analog of {@link java.lang.Runnable}. Instances of concrete class
{@link java.util.concurrent.FutureTask} may be submitted to Executors
to asynchronously start a potentially long-running computation, query
to determine if its execution has completed, or cancel it.  The {@link
java.util.concurrent.CancellableTask} class provides similar control
for actions that do not bear results.

<h2>Queues</h2>

The java.util.concurrent {@link
java.util.concurrent.ConcurrentLinkedQueue} class supplies an
efficient scalable thread-safe non-blocking FIFO queue.  Five
implementations in java.util.concurrent support the extended {@link
java.util.concurrent.BlockingQueue} interface, that defines blocking
versions of put and take: {@link
java.util.concurrent.LinkedBlockingQueue}, {@link
java.util.concurrent.ArrayBlockingQueue}, {@link
java.util.concurrent.SynchronousQueue}, {@link
java.util.concurrent.PriorityBlockingQueue}, and {@link
java.util.concurrent.DelayQueue}. The different classes cover the most
common usage contexts for producer-consumer, messaging, parallel
tasking, and related concurrent designs.


<h2>Timing</h2>

The {@link java.util.concurrent.TimeUnit} class provides multiple
granularities (including nanoseconds) for specifying and controlling
time-out based operations. Most classes in the package contain
operations based on time-outs in addition to indefinite waits.  In all
cases that time-outs are used, the time-out specifies the minimum time
that the method should wait before indicating that it
timed-out. Implementations make a &quot;best effort&quot; to detect
time-outs as soon as possible after they occur. However, an indefinite
amount of time may elapse between a time-out being detected and a
thread actually executing again after that time-out.

<h2>Synchronizers</h2>

Five classes aid common special-purpose synchronization idioms.
{@link java.util.concurrent.Semaphore} is a classic concurrency tool.
{@link java.util.concurrent.CountDownLatch} is very simple yet very
common utility for blocking until a single signal, event, or condition
holds.  A {@link java.util.concurrent.CyclicBarrier} is a resettable
multiway synchronization point common in some styles of parallel
programming. An {@link java.util.concurrent.Exchanger} allows two
threads to exchange objects at a rendezvous point.

<h2>Concurrent Collections</h2>

Besides Queues, this package supplies a few Collection implementations
designed for use in multithreaded contexts: {@link
java.util.concurrent.ConcurrentHashMap}, {@link
java.util.concurrent.CopyOnWriteArrayList}, and {@link
java.util.concurrent.CopyOnWriteArraySet}.

<p>The "Concurrent" prefix used with some classes in this package is a
shorthand indicating several differences from similar "synchronized"
classes. For example <tt>java.util.Hashtable</tt> and
<tt>Collections.synchronizedMap(new HashMap())</tt> are
synchronized. But {@link java.util.concurrent.ConcurrentHashMap} is
"concurrent".  A concurrent collection is thread-safe, but not
governed by a single exclusion lock. In the particular case of
ConcurrentHashMap, it safely permits any number of concurrent reads as
well as a tunable number of concurrent writes.  "Synchronized" classes
can be useful when you need to prevent all access to a collection via
a single lock, at the expense of poorer scalability. In other cases in
which multiple threads are expected to access a common collection,
"concurrent" versions are normally preferable. And unsynchronized
collections are preferable when either collections are unshared, or
are accessible only when holding other locks.

<p> Most concurrent Collection implementations (including most Queues)
also differ from the usual java.util conventions in that their Iterators
provide <em>weakly consistent</em> rather than fast-fail traversal. A
weakly consistent iterator is thread-safe, but does not necessarily
freeze the collection while iterating, so it may (or may not) reflect
any updates since the iterator was created.

</body> </html>
Revision:	1.10
Committed:	Mon Nov 3 13:49:56 2003 UTC (20 years, 7 months ago) by dl
Content type:	text/html
Branch:	MAIN
CVS Tags:	JSR166_NOV3_FREEZE
Changes since 1.9:	+3 -4 lines
Log Message:	Merged FairSemaphore into Semaphore
#	User	Rev	Content
1	dl	1.1	<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
2			<html> <head>
3			<title>Concurrency Utilities</title>
4			</head>
5
6			<body>
7
8	dl	1.3	<p> Utility classes commonly useful in concurrent programming. This
9			package includes a few small standardized extensible frameworks, as
10			well as some classes that provide useful functionality and are
11			otherwise tedious or difficult to implement. Here are brief
12			descriptions of the main components. See also the <tt>locks</tt> and
13			<tt>atomic</tt> packages.
14	dl	1.1
15			<h2>Executors</h2>
16
17			{@link java.util.concurrent.Executor} is a simple standardized
18			interface for defining custom thread-like subsystems, including thread
19	dl	1.9	pools, asynchronous IO, and lightweight task frameworks. Depending on
20			which concrete Executor class is being used, tasks may execute in a
21			newly created thread, an existing task-execution thread, or the thread
22	dl	1.1	calling <tt>execute()</tt>, and may execute sequentially or
23	dl	1.9	concurrently.
24	dl	1.1
25			<p> {@link java.util.concurrent.ExecutorService} provides a more
26			complete framework for executing Runnables. An ExecutorService
27			manages queueing and scheduling of tasks, and allows controlled
28			shutdown. The two primary implementations of ExecutorService are
29	dl	1.5	{@link java.util.concurrent.ThreadPoolExecutor}, a tunable and
30	dl	1.1	flexible thread pool and {@link
31			java.util.concurrent.ScheduledExecutor}, which adds support for
32	dl	1.9	delayed and periodic task execution. The {@link
33			java.util.concurrent.Executors} class provides factory methods for the
34			most common kinds and configurations of Executors, as well as a few
35			utility methods for using them.
36
37			<p> Executors may be used with threads that compute functions
38			returning results. A {@link java.util.concurrent.Future} returns the
39			results of a {@link java.util.concurrent.Callable}, the result-bearing
40			analog of {@link java.lang.Runnable}. Instances of concrete class
41			{@link java.util.concurrent.FutureTask} may be submitted to Executors
42			to asynchronously start a potentially long-running computation, query
43			to determine if its execution has completed, or cancel it. The {@link
44			java.util.concurrent.CancellableTask} class provides similar control
45			for actions that do not bear results.
46	dl	1.1
47			<h2>Queues</h2>
48
49	dl	1.6	The java.util.concurrent {@link
50	dl	1.1	java.util.concurrent.ConcurrentLinkedQueue} class supplies an
51	dl	1.6	efficient scalable thread-safe non-blocking FIFO queue. Five
52			implementations in java.util.concurrent support the extended {@link
53			java.util.concurrent.BlockingQueue} interface, that defines blocking
54			versions of put and take: {@link
55	dl	1.1	java.util.concurrent.LinkedBlockingQueue}, {@link
56			java.util.concurrent.ArrayBlockingQueue}, {@link
57			java.util.concurrent.SynchronousQueue}, {@link
58			java.util.concurrent.PriorityBlockingQueue}, and {@link
59	dl	1.2	java.util.concurrent.DelayQueue}. The different classes cover the most
60			common usage contexts for producer-consumer, messaging, parallel
61			tasking, and related concurrent designs.
62	dl	1.1
63
64			<h2>Timing</h2>
65
66			The {@link java.util.concurrent.TimeUnit} class provides multiple
67	dl	1.2	granularities (including nanoseconds) for specifying and controlling
68	dl	1.9	time-out based operations. Most classes in the package contain
69			operations based on time-outs in addition to indefinite waits. In all
70			cases that time-outs are used, the time-out specifies the minimum time
71			that the method should wait before indicating that it
72			timed-out. Implementations make a "best effort" to detect
73			time-outs as soon as possible after they occur. However, an indefinite
74			amount of time may elapse between a time-out being detected and a
75			thread actually executing again after that time-out.
76	dholmes	1.4
77	dl	1.1	<h2>Synchronizers</h2>
78
79			Five classes aid common special-purpose synchronization idioms.
80	dl	1.10	{@link java.util.concurrent.Semaphore} is a classic concurrency tool.
81	dl	1.1	{@link java.util.concurrent.CountDownLatch} is very simple yet very
82			common utility for blocking until a single signal, event, or condition
83	dl	1.10	holds. A {@link java.util.concurrent.CyclicBarrier} is a resettable
84			multiway synchronization point common in some styles of parallel
85	dl	1.1	programming. An {@link java.util.concurrent.Exchanger} allows two
86			threads to exchange objects at a rendezvous point.
87
88			<h2>Concurrent Collections</h2>
89
90			Besides Queues, this package supplies a few Collection implementations
91			designed for use in multithreaded contexts: {@link
92			java.util.concurrent.ConcurrentHashMap}, {@link
93			java.util.concurrent.CopyOnWriteArrayList}, and {@link
94			java.util.concurrent.CopyOnWriteArraySet}.
95
96	dl	1.6	<p>The "Concurrent" prefix used with some classes in this package is a
97			shorthand indicating several differences from similar "synchronized"
98	dl	1.1	classes. For example <tt>java.util.Hashtable</tt> and
99			<tt>Collections.synchronizedMap(new HashMap())</tt> are
100	dl	1.6	synchronized. But {@link java.util.concurrent.ConcurrentHashMap} is
101			"concurrent". A concurrent collection is thread-safe, but not
102			governed by a single exclusion lock. In the particular case of
103			ConcurrentHashMap, it safely permits any number of concurrent reads as
104	dl	1.9	well as a tunable number of concurrent writes. "Synchronized" classes
105			can be useful when you need to prevent all access to a collection via
106			a single lock, at the expense of poorer scalability. In other cases in
107			which multiple threads are expected to access a common collection,
108			"concurrent" versions are normally preferable. And unsynchronized
109			collections are preferable when either collections are unshared, or
110			are accessible only when holding other locks.
111	dl	1.1
112			<p> Most concurrent Collection implementations (including most Queues)
113			also differ from the usual java.util conventions in that their Iterators
114			provide <em>weakly consistent</em> rather than fast-fail traversal. A
115			weakly consistent iterator is thread-safe, but does not necessarily
116			freeze the collection while iterating, so it may (or may not) reflect
117			any updates since the iterator was created.
118
119			</body> </html>