/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Sun designates this * particular file as subject to the "Classpath" exception as provided * by Sun in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, * CA 95054 USA or visit www.sun.com if you need additional information or * have any questions. */ /* * This file is available under and governed by the GNU General Public * License version 2 only, as published by the Free Software Foundation. * However, the following notice accompanied the original version of this * file: * * 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 */ /** * 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. * *

Executors

* * Interfaces. * * {@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. * *

* * Implementations. * * 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. * *

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. * *

Queues

* * The {@link java.util.concurrent.ConcurrentLinkedQueue} class * supplies an efficient scalable thread-safe non-blocking FIFO * queue. * *

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. * *

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. * *

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. * *

Timing

* * 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}. * *

Synchronizers

* * Five classes aid common special-purpose synchronization idioms. * * *

Concurrent Collections

* * 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. *

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. * *

Most concurrent Collection implementations (including most * Queues) also differ from the usual java.util conventions in that * their Iterators provide weakly consistent 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. * *

Memory Consistency Properties

* * * Chapter 17 of the Java Language Specification defines the * happens-before 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 happens-before the read operation. The * {@code synchronized} and {@code volatile} constructs, as well as the * {@code Thread.start()} and {@code Thread.join()} methods, can form * happens-before relationships. In particular: * * * * * The methods of all classes in {@code java.util.concurrent} and its * subpackages extend these guarantees to higher-level * synchronization. In particular: * * * * @since 1.5 */ package java.util.concurrent;