jaroslav@1890: /* jaroslav@1890: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jaroslav@1890: * jaroslav@1890: * This code is free software; you can redistribute it and/or modify it jaroslav@1890: * under the terms of the GNU General Public License version 2 only, as jaroslav@1890: * published by the Free Software Foundation. Oracle designates this jaroslav@1890: * particular file as subject to the "Classpath" exception as provided jaroslav@1890: * by Oracle in the LICENSE file that accompanied this code. jaroslav@1890: * jaroslav@1890: * This code is distributed in the hope that it will be useful, but WITHOUT jaroslav@1890: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jaroslav@1890: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jaroslav@1890: * version 2 for more details (a copy is included in the LICENSE file that jaroslav@1890: * accompanied this code). jaroslav@1890: * jaroslav@1890: * You should have received a copy of the GNU General Public License version jaroslav@1890: * 2 along with this work; if not, write to the Free Software Foundation, jaroslav@1890: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jaroslav@1890: * jaroslav@1890: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jaroslav@1890: * or visit www.oracle.com if you need additional information or have any jaroslav@1890: * questions. jaroslav@1890: */ jaroslav@1890: jaroslav@1890: /* jaroslav@1890: * This file is available under and governed by the GNU General Public jaroslav@1890: * License version 2 only, as published by the Free Software Foundation. jaroslav@1890: * However, the following notice accompanied the original version of this jaroslav@1890: * file: jaroslav@1890: * jaroslav@1890: * Written by Doug Lea with assistance from members of JCP JSR-166 jaroslav@1890: * Expert Group and released to the public domain, as explained at jaroslav@1890: * http://creativecommons.org/publicdomain/zero/1.0/ jaroslav@1890: */ jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Utility classes commonly useful in concurrent programming. This jaroslav@1890: * package includes a few small standardized extensible frameworks, as jaroslav@1890: * well as some classes that provide useful functionality and are jaroslav@1890: * otherwise tedious or difficult to implement. Here are brief jaroslav@1890: * descriptions of the main components. See also the jaroslav@1890: * {@link java.util.concurrent.locks} and jaroslav@1890: * {@link java.util.concurrent.atomic} packages. jaroslav@1890: * jaroslav@1890: *

Executors

jaroslav@1890: * jaroslav@1890: * Interfaces. jaroslav@1890: * jaroslav@1890: * {@link java.util.concurrent.Executor} is a simple standardized jaroslav@1890: * interface for defining custom thread-like subsystems, including jaroslav@1890: * thread pools, asynchronous IO, and lightweight task frameworks. jaroslav@1890: * Depending on which concrete Executor class is being used, tasks may jaroslav@1890: * execute in a newly created thread, an existing task-execution thread, jaroslav@1890: * or the thread calling {@link java.util.concurrent.Executor#execute jaroslav@1890: * execute}, and may execute sequentially or concurrently. jaroslav@1890: * jaroslav@1890: * {@link java.util.concurrent.ExecutorService} provides a more jaroslav@1890: * complete asynchronous task execution framework. An jaroslav@1890: * ExecutorService manages queuing and scheduling of tasks, jaroslav@1890: * and allows controlled shutdown. jaroslav@1890: * jaroslav@1890: * The {@link java.util.concurrent.ScheduledExecutorService} jaroslav@1890: * subinterface and associated interfaces add support for jaroslav@1890: * delayed and periodic task execution. ExecutorServices jaroslav@1890: * provide methods arranging asynchronous execution of any jaroslav@1890: * function expressed as {@link java.util.concurrent.Callable}, jaroslav@1890: * the result-bearing analog of {@link java.lang.Runnable}. jaroslav@1890: * jaroslav@1890: * A {@link java.util.concurrent.Future} returns the results of jaroslav@1890: * a function, allows determination of whether execution has jaroslav@1890: * completed, and provides a means to cancel execution. jaroslav@1890: * jaroslav@1890: * A {@link java.util.concurrent.RunnableFuture} is a {@code Future} jaroslav@1890: * that possesses a {@code run} method that upon execution, jaroslav@1890: * sets its results. jaroslav@1890: * jaroslav@1890: *

jaroslav@1890: * jaroslav@1890: * Implementations. jaroslav@1890: * jaroslav@1890: * Classes {@link java.util.concurrent.ThreadPoolExecutor} and jaroslav@1890: * {@link java.util.concurrent.ScheduledThreadPoolExecutor} jaroslav@1890: * provide tunable, flexible thread pools. jaroslav@1890: * jaroslav@1890: * The {@link java.util.concurrent.Executors} class provides jaroslav@1890: * factory methods for the most common kinds and configurations jaroslav@1890: * of Executors, as well as a few utility methods for using jaroslav@1890: * them. Other utilities based on {@code Executors} include the jaroslav@1890: * concrete class {@link java.util.concurrent.FutureTask} jaroslav@1890: * providing a common extensible implementation of Futures, and jaroslav@1890: * {@link java.util.concurrent.ExecutorCompletionService}, that jaroslav@1890: * assists in coordinating the processing of groups of jaroslav@1890: * asynchronous tasks. jaroslav@1890: * jaroslav@1890: *

Class {@link java.util.concurrent.ForkJoinPool} provides an jaroslav@1890: * Executor primarily designed for processing instances of {@link jaroslav@1890: * java.util.concurrent.ForkJoinTask} and its subclasses. These jaroslav@1890: * classes employ a work-stealing scheduler that attains high jaroslav@1890: * throughput for tasks conforming to restrictions that often hold in jaroslav@1890: * computation-intensive parallel processing. jaroslav@1890: * jaroslav@1890: *

Queues

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

Five implementations in {@code java.util.concurrent} support jaroslav@1890: * the extended {@link java.util.concurrent.BlockingQueue} jaroslav@1890: * interface, that defines blocking versions of put and take: jaroslav@1890: * {@link java.util.concurrent.LinkedBlockingQueue}, jaroslav@1890: * {@link java.util.concurrent.ArrayBlockingQueue}, jaroslav@1890: * {@link java.util.concurrent.SynchronousQueue}, jaroslav@1890: * {@link java.util.concurrent.PriorityBlockingQueue}, and jaroslav@1890: * {@link java.util.concurrent.DelayQueue}. jaroslav@1890: * The different classes cover the most common usage contexts jaroslav@1890: * for producer-consumer, messaging, parallel tasking, and jaroslav@1890: * related concurrent designs. jaroslav@1890: * jaroslav@1890: *

Extended interface {@link java.util.concurrent.TransferQueue}, jaroslav@1890: * and implementation {@link java.util.concurrent.LinkedTransferQueue} jaroslav@1890: * introduce a synchronous {@code transfer} method (along with related jaroslav@1890: * features) in which a producer may optionally block awaiting its jaroslav@1890: * consumer. jaroslav@1890: * jaroslav@1890: *

The {@link java.util.concurrent.BlockingDeque} interface jaroslav@1890: * extends {@code BlockingQueue} to support both FIFO and LIFO jaroslav@1890: * (stack-based) operations. jaroslav@1890: * Class {@link java.util.concurrent.LinkedBlockingDeque} jaroslav@1890: * provides an implementation. jaroslav@1890: * jaroslav@1890: *

Timing

jaroslav@1890: * jaroslav@1890: * The {@link java.util.concurrent.TimeUnit} class provides jaroslav@1890: * multiple granularities (including nanoseconds) for jaroslav@1890: * specifying and controlling time-out based operations. Most jaroslav@1890: * classes in the package contain operations based on time-outs jaroslav@1890: * in addition to indefinite waits. In all cases that jaroslav@1890: * time-outs are used, the time-out specifies the minimum time jaroslav@1890: * that the method should wait before indicating that it jaroslav@1890: * timed-out. Implementations make a "best effort" jaroslav@1890: * to detect time-outs as soon as possible after they occur. jaroslav@1890: * However, an indefinite amount of time may elapse between a jaroslav@1890: * time-out being detected and a thread actually executing jaroslav@1890: * again after that time-out. All methods that accept timeout jaroslav@1890: * parameters treat values less than or equal to zero to mean jaroslav@1890: * not to wait at all. To wait "forever", you can use a value jaroslav@1890: * of {@code Long.MAX_VALUE}. jaroslav@1890: * jaroslav@1890: *

Synchronizers

jaroslav@1890: * jaroslav@1890: * Five classes aid common special-purpose synchronization idioms. jaroslav@1890: * jaroslav@1890: * jaroslav@1890: *

Concurrent Collections

jaroslav@1890: * jaroslav@1890: * Besides Queues, this package supplies Collection implementations jaroslav@1890: * designed for use in multithreaded contexts: jaroslav@1890: * {@link java.util.concurrent.ConcurrentHashMap}, jaroslav@1890: * {@link java.util.concurrent.ConcurrentSkipListMap}, jaroslav@1890: * {@link java.util.concurrent.ConcurrentSkipListSet}, jaroslav@1890: * {@link java.util.concurrent.CopyOnWriteArrayList}, and jaroslav@1890: * {@link java.util.concurrent.CopyOnWriteArraySet}. jaroslav@1890: * When many threads are expected to access a given collection, a jaroslav@1890: * {@code ConcurrentHashMap} is normally preferable to a synchronized jaroslav@1890: * {@code HashMap}, and a {@code ConcurrentSkipListMap} is normally jaroslav@1890: * preferable to a synchronized {@code TreeMap}. jaroslav@1890: * A {@code CopyOnWriteArrayList} is preferable to a synchronized jaroslav@1890: * {@code ArrayList} when the expected number of reads and traversals jaroslav@1890: * greatly outnumber the number of updates to a list. jaroslav@1890: jaroslav@1890: *

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

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

Memory Consistency Properties

jaroslav@1890: * jaroslav@1890: * Chapter 17 of jaroslav@1890: * The Java™ Language Specification jaroslav@1890: * defines the jaroslav@1890: * happens-before relation on memory operations such as reads and jaroslav@1890: * writes of shared variables. The results of a write by one thread are jaroslav@1890: * guaranteed to be visible to a read by another thread only if the write jaroslav@1890: * operation happens-before the read operation. The jaroslav@1890: * {@code synchronized} and {@code volatile} constructs, as well as the jaroslav@1890: * {@code Thread.start()} and {@code Thread.join()} methods, can form jaroslav@1890: * happens-before relationships. In particular: jaroslav@1890: * jaroslav@1890: * jaroslav@1890: * jaroslav@1890: * jaroslav@1890: * The methods of all classes in {@code java.util.concurrent} and its jaroslav@1890: * subpackages extend these guarantees to higher-level jaroslav@1890: * synchronization. In particular: jaroslav@1890: * jaroslav@1890: * jaroslav@1890: * jaroslav@1890: * @since 1.5 jaroslav@1890: */ jaroslav@1890: package java.util.concurrent;