diff options
Diffstat (limited to 'src/forkjoin/scala/concurrent/forkjoin/package-info.java')
| -rw-r--r-- | src/forkjoin/scala/concurrent/forkjoin/package-info.java | 281 |
1 files changed, 261 insertions, 20 deletions
diff --git a/src/forkjoin/scala/concurrent/forkjoin/package-info.java b/src/forkjoin/scala/concurrent/forkjoin/package-info.java index b8fa0fad02..33df96f186 100644 --- a/src/forkjoin/scala/concurrent/forkjoin/package-info.java +++ b/src/forkjoin/scala/concurrent/forkjoin/package-info.java @@ -1,29 +1,270 @@ /* * Written by Doug Lea with assistance from members of JCP JSR-166 * Expert Group and released to the public domain, as explained at - * http://creativecommons.org/licenses/publicdomain + * http://creativecommons.org/publicdomain/zero/1.0/ */ - /** - * Preview versions of classes targeted for Java 7. Includes a - * fine-grained parallel computation framework: ForkJoinTasks and - * their related support classes provide a very efficient basis for - * obtaining platform-independent parallel speed-ups of - * computation-intensive operations. They are not a full substitute - * for the kinds of arbitrary processing supported by Executors or - * Threads. However, when applicable, they typically provide - * significantly greater performance on multiprocessor platforms. - * - * <p> Candidates for fork/join processing mainly include those that - * can be expressed using parallel divide-and-conquer techniques: To - * solve a problem, break it in two (or more) parts, and then solve - * those parts in parallel, continuing on in this way until the - * problem is too small to be broken up, so is solved directly. The - * underlying <em>work-stealing</em> framework makes subtasks - * available to other threads (normally one per CPU), that help - * complete the tasks. In general, the most efficient ForkJoinTasks - * are those that directly implement this algorithmic design pattern. + * 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 + * {@link java.util.concurrent.locks} and + * {@link java.util.concurrent.atomic} 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 {@link java.util.concurrent.Executor#execute + * execute}, 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 {@code Future} + * that possesses a {@code run} 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 {@code 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. + * + * <p>Class {@link java.util.concurrent.ForkJoinPool} provides an + * Executor primarily designed for processing instances of {@link + * java.util.concurrent.ForkJoinTask} and its subclasses. These + * classes employ a work-stealing scheduler that attains high + * throughput for tasks conforming to restrictions that often hold in + * computation-intensive parallel processing. + * + * <h2>Queues</h2> + * + * The {@link java.util.concurrent.ConcurrentLinkedQueue} class + * supplies an efficient scalable thread-safe non-blocking FIFO + * queue. + * + * <p>Five implementations in {@code 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. + * + * <p> Extended interface {@link java.util.concurrent.TransferQueue}, + * and implementation {@link java.util.concurrent.LinkedTransferQueue} + * introduce a synchronous {@code transfer} method (along with related + * features) in which a producer may optionally block awaiting its + * consumer. + * + * <p>The {@link java.util.concurrent.BlockingDeque} interface + * extends {@code BlockingQueue} 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 {@code Long.MAX_VALUE}. + * + * <h2>Synchronizers</h2> + * + * Five classes aid common special-purpose synchronization idioms. + * <ul> + * + * <li>{@link java.util.concurrent.Semaphore} is a classic concurrency tool. + * + * <li>{@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. + * + * <li>A {@link java.util.concurrent.CyclicBarrier} is a resettable + * multiway synchronization point useful in some styles of parallel + * programming. + * + * <li>A {@link java.util.concurrent.Phaser} provides + * a more flexible form of barrier that may be used to control phased + * computation among multiple threads. + * + * <li>An {@link java.util.concurrent.Exchanger} allows two threads to + * exchange objects at a rendezvous point, and is useful in several + * pipeline designs. + * + * </ul> + * + * <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 + * {@code ConcurrentHashMap} is normally preferable to a synchronized + * {@code HashMap}, and a {@code ConcurrentSkipListMap} is normally + * preferable to a synchronized {@code TreeMap}. + * A {@code CopyOnWriteArrayList} is preferable to a synchronized + * {@code ArrayList} 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 {@code java.util.Hashtable} and + * {@code Collections.synchronizedMap(new HashMap())} 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. + * + * <h2><a name="MemoryVisibility">Memory Consistency Properties</a></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} and + * {@code Phaser.awaitAdvance} (as well as its variants) + * <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 */ package scala.concurrent.forkjoin; |