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: * - {@link java.util.concurrent.Semaphore} is a classic concurrency tool.
jaroslav@1890: *
jaroslav@1890: *
- {@link java.util.concurrent.CountDownLatch} is a very simple yet
jaroslav@1890: * very common utility for blocking until a given number of signals,
jaroslav@1890: * events, or conditions hold.
jaroslav@1890: *
jaroslav@1890: *
- A {@link java.util.concurrent.CyclicBarrier} is a resettable
jaroslav@1890: * multiway synchronization point useful in some styles of parallel
jaroslav@1890: * programming.
jaroslav@1890: *
jaroslav@1890: *
- A {@link java.util.concurrent.Phaser} provides
jaroslav@1890: * a more flexible form of barrier that may be used to control phased
jaroslav@1890: * computation among multiple threads.
jaroslav@1890: *
jaroslav@1890: *
- An {@link java.util.concurrent.Exchanger} allows two threads to
jaroslav@1890: * exchange objects at a rendezvous point, and is useful in several
jaroslav@1890: * pipeline designs.
jaroslav@1890: *
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: *
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: * - Each action in a thread happens-before every action in that
jaroslav@1890: * thread that comes later in the program's order.
jaroslav@1890: *
jaroslav@1890: *
- An unlock ({@code synchronized} block or method exit) of a
jaroslav@1890: * monitor happens-before every subsequent lock ({@code synchronized}
jaroslav@1890: * block or method entry) of that same monitor. And because
jaroslav@1890: * the happens-before relation is transitive, all actions
jaroslav@1890: * of a thread prior to unlocking happen-before all actions
jaroslav@1890: * subsequent to any thread locking that monitor.
jaroslav@1890: *
jaroslav@1890: *
- A write to a {@code volatile} field happens-before every
jaroslav@1890: * subsequent read of that same field. Writes and reads of
jaroslav@1890: * {@code volatile} fields have similar memory consistency effects
jaroslav@1890: * as entering and exiting monitors, but do not entail
jaroslav@1890: * mutual exclusion locking.
jaroslav@1890: *
jaroslav@1890: *
- A call to {@code start} on a thread happens-before any
jaroslav@1890: * action in the started thread.
jaroslav@1890: *
jaroslav@1890: *
- All actions in a thread happen-before any other thread
jaroslav@1890: * successfully returns from a {@code join} on that thread.
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: * - Actions in a thread prior to placing an object into any concurrent
jaroslav@1890: * collection happen-before actions subsequent to the access or
jaroslav@1890: * removal of that element from the collection in another thread.
jaroslav@1890: *
jaroslav@1890: *
- Actions in a thread prior to the submission of a {@code Runnable}
jaroslav@1890: * to an {@code Executor} happen-before its execution begins.
jaroslav@1890: * Similarly for {@code Callables} submitted to an {@code ExecutorService}.
jaroslav@1890: *
jaroslav@1890: *
- Actions taken by the asynchronous computation represented by a
jaroslav@1890: * {@code Future} happen-before actions subsequent to the
jaroslav@1890: * retrieval of the result via {@code Future.get()} in another thread.
jaroslav@1890: *
jaroslav@1890: *
- Actions prior to "releasing" synchronizer methods such as
jaroslav@1890: * {@code Lock.unlock}, {@code Semaphore.release}, and
jaroslav@1890: * {@code CountDownLatch.countDown} happen-before actions
jaroslav@1890: * subsequent to a successful "acquiring" method such as
jaroslav@1890: * {@code Lock.lock}, {@code Semaphore.acquire},
jaroslav@1890: * {@code Condition.await}, and {@code CountDownLatch.await} on the
jaroslav@1890: * same synchronizer object in another thread.
jaroslav@1890: *
jaroslav@1890: *
- For each pair of threads that successfully exchange objects via
jaroslav@1890: * an {@code Exchanger}, actions prior to the {@code exchange()}
jaroslav@1890: * in each thread happen-before those subsequent to the
jaroslav@1890: * corresponding {@code exchange()} in another thread.
jaroslav@1890: *
jaroslav@1890: *
- Actions prior to calling {@code CyclicBarrier.await} and
jaroslav@1890: * {@code Phaser.awaitAdvance} (as well as its variants)
jaroslav@1890: * happen-before actions performed by the barrier action, and
jaroslav@1890: * actions performed by the barrier action happen-before actions
jaroslav@1890: * subsequent to a successful return from the corresponding {@code await}
jaroslav@1890: * in other threads.
jaroslav@1890: *
jaroslav@1890: *
jaroslav@1890: *
jaroslav@1890: * @since 1.5
jaroslav@1890: */
jaroslav@1890: package java.util.concurrent;