diff options
Diffstat (limited to 'libjava/classpath/external/jsr166/java/util/concurrent/package.html')
| -rw-r--r-- | libjava/classpath/external/jsr166/java/util/concurrent/package.html | 222 |
1 files changed, 0 insertions, 222 deletions
diff --git a/libjava/classpath/external/jsr166/java/util/concurrent/package.html b/libjava/classpath/external/jsr166/java/util/concurrent/package.html deleted file mode 100644 index 20227e1fece..00000000000 --- a/libjava/classpath/external/jsr166/java/util/concurrent/package.html +++ /dev/null @@ -1,222 +0,0 @@ -<!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> - -<b>Interfaces.</b> {@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. {@link -java.util.concurrent.ExecutorService} provides a more complete -asynchronous task execution framework. An ExecutorService manages -queuing and scheduling of tasks, and allows controlled shutdown. The -{@link java.util.concurrent.ScheduledExecutorService} subinterface -and associated interfaces add support for delayed and periodic task execution. -ExecutorServices provide methods arranging asynchronous execution of -any function expressed as {@link java.util.concurrent.Callable}, the -result-bearing analog of {@link java.lang.Runnable}. A {@link -java.util.concurrent.Future} returns the results of a function, allows -determination of whether execution has completed, and provides a means to -cancel execution. A {@link java.util.concurrent.RunnableFuture} is -a Future that possesses a <tt>run</tt> method that upon execution, -sets its results. - -<p> - -<b>Implementations.</b> Classes {@link -java.util.concurrent.ThreadPoolExecutor} and {@link -java.util.concurrent.ScheduledThreadPoolExecutor} provide tunable, -flexible thread pools. 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. Other utilities based on Executors include the concrete -class {@link java.util.concurrent.FutureTask} providing a common -extensible implementation of Futures, and {@link -java.util.concurrent.ExecutorCompletionService}, that assists in -coordinating the processing of groups of asynchronous tasks. - -<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. The {@link -java.util.concurrent.BlockingDeque} interface extends -<tt>BlockingQueue</tt> to support both FIFO and LIFO (stack-based) -operations. Class {@link java.util.concurrent.LinkedBlockingDeque} -provides an implementation. - - -<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 "best effort" 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. All methods -that accept timeout parameters treat values less than or equal to -zero to mean not to wait at all. To wait "forever", you can use -a value of <tt>Long.MAX_VALUE</tt>. - -<h2>Synchronizers</h2> - -Four classes aid common special-purpose synchronization idioms. -{@link java.util.concurrent.Semaphore} is a classic concurrency tool. -{@link java.util.concurrent.CountDownLatch} is a very simple yet very -common utility for blocking until a given number of signals, events, -or conditions hold. A {@link java.util.concurrent.CyclicBarrier} is a -resettable multiway synchronization point useful in some styles of -parallel programming. An {@link java.util.concurrent.Exchanger} allows -two threads to exchange objects at a rendezvous point, and is useful -in several pipeline designs. - -<h2>Concurrent Collections</h2> - -Besides Queues, this package supplies Collection implementations -designed for use in multithreaded contexts: -{@link java.util.concurrent.ConcurrentHashMap}, -{@link java.util.concurrent.ConcurrentSkipListMap}, -{@link java.util.concurrent.ConcurrentSkipListSet}, -{@link java.util.concurrent.CopyOnWriteArrayList}, and -{@link java.util.concurrent.CopyOnWriteArraySet}. -When many threads are expected to access a given collection, -a <tt>ConcurrentHashMap</tt> is normally preferable to -a synchronized <tt>HashMap</tt>, and a -<tt>ConcurrentSkipListMap</tt> is normally preferable -to a synchronized <tt>TreeMap</tt>. A -<tt>CopyOnWriteArrayList</tt> is preferable to -a synchronized <tt>ArrayList</tt> when the expected number of reads -and traversals greatly outnumber the number of updates to a list. - -<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. - -<a name="MemoryVisibility"> -<h2> Memory Consistency Properties </h2> - -<a href="http://java.sun.com/docs/books/jls/third_edition/html/memory.html"> -Chapter 17 of the Java Language Specification</a> defines the -<i>happens-before</i> relation on memory operations such as reads and -writes of shared variables. The results of a write by one thread are -guaranteed to be visible to a read by another thread only if the write -operation <i>happens-before</i> the read operation. The -{@code synchronized} and {@code volatile} constructs, as well as the -{@code Thread.start()} and {@code Thread.join()} methods, can form -<i>happens-before</i> relationships. In particular: - -<ul> - <li>Each action in a thread <i>happens-before</i> every action in that - thread that comes later in the program's order. - - <li>An unlock ({@code synchronized} block or method exit) of a - monitor <i>happens-before</i> every subsequent lock ({@code synchronized} - block or method entry) of that same monitor. And because - the <i>happens-before</i> relation is transitive, all actions - of a thread prior to unlocking <i>happen-before</i> all actions - subsequent to any thread locking that monitor. - - <li>A write to a {@code volatile} field <i>happens-before</i> every - subsequent read of that same field. Writes and reads of - {@code volatile} fields have similar memory consistency effects - as entering and exiting monitors, but do <em>not</em> entail - mutual exclusion locking. - - <li>A call to {@code start} on a thread <i>happens-before</i> any action in the - started thread. - - <li>All actions in a thread <i>happen-before</i> any other thread - successfully returns from a {@code join} on that thread. - -</ul> - - -The methods of all classes in {@code java.util.concurrent} and its -subpackages extend these guarantees to higher-level -synchronization. In particular: - -<ul> - - <li>Actions in a thread prior to placing an object into any concurrent - collection <i>happen-before</i> actions subsequent to the access or - removal of that element from the collection in another thread. - - <li>Actions in a thread prior to the submission of a {@code Runnable} - to an {@code Executor} <i>happen-before</i> its execution begins. - Similarly for {@code Callables} submitted to an {@code ExecutorService}. - - <li>Actions taken by the asynchronous computation represented by a - {@code Future} <i>happen-before</i> actions subsequent to the - retrieval of the result via {@code Future.get()} in another thread. - - <li>Actions prior to "releasing" synchronizer methods such as - {@code Lock.unlock}, {@code Semaphore.release}, and - {@code CountDownLatch.countDown} <i>happen-before</i> actions - subsequent to a successful "acquiring" method such as - {@code Lock.lock}, {@code Semaphore.acquire}, - {@code Condition.await}, and {@code CountDownLatch.await} on the - same synchronizer object in another thread. - - <li>For each pair of threads that successfully exchange objects via - an {@code Exchanger}, actions prior to the {@code exchange()} - in each thread <i>happen-before</i> those subsequent to the - corresponding {@code exchange()} in another thread. - - <li>Actions prior to calling {@code CyclicBarrier.await} - <i>happen-before</i> actions performed by the barrier action, and - actions performed by the barrier action <i>happen-before</i> actions - subsequent to a successful return from the corresponding {@code await} - in other threads. - -</ul> - -@since 1.5 - -</body> </html> |
