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, 20 insertions, 261 deletions
diff --git a/src/forkjoin/scala/concurrent/forkjoin/package-info.java b/src/forkjoin/scala/concurrent/forkjoin/package-info.java index 33df96f186..b8fa0fad02 100644 --- a/src/forkjoin/scala/concurrent/forkjoin/package-info.java +++ b/src/forkjoin/scala/concurrent/forkjoin/package-info.java @@ -1,270 +1,29 @@ /* * 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/publicdomain/zero/1.0/ + * http://creativecommons.org/licenses/publicdomain */ + /** - * 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> + * 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. * - * @since 1.5 */ package scala.concurrent.forkjoin; |