1 /*

     2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     3  *

     4  * This code is free software; you can redistribute it and/or modify it

     5  * under the terms of the GNU General Public License version 2 only, as

     6  * published by the Free Software Foundation.  Sun designates this

     7  * particular file as subject to the "Classpath" exception as provided

     8  * by Sun in the LICENSE file that accompanied this code.

     9  *

    10  * This code is distributed in the hope that it will be useful, but WITHOUT

    11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    13  * version 2 for more details (a copy is included in the LICENSE file that

    14  * accompanied this code).

    15  *

    16  * You should have received a copy of the GNU General Public License version

    17  * 2 along with this work; if not, write to the Free Software Foundation,

    18  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    19  *

    20  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    21  * CA 95054 USA or visit www.sun.com if you need additional information or

    22  * have any questions.

    23  */

    24 

    25 /*

    26  * This file is available under and governed by the GNU General Public

    27  * License version 2 only, as published by the Free Software Foundation.

    28  * However, the following notice accompanied the original version of this

    29  * file:

    30  *

    31  * Written by Doug Lea with assistance from members of JCP JSR-166

    32  * Expert Group and released to the public domain, as explained at

    33  * http://creativecommons.org/licenses/publicdomain

    34  */

    35 

    36 /**

    37  * Utility classes commonly useful in concurrent programming.  This

    38  * package includes a few small standardized extensible frameworks, as

    39  * well as some classes that provide useful functionality and are

    40  * otherwise tedious or difficult to implement.  Here are brief

    41  * descriptions of the main components.  See also the

    42  * {@link java.util.concurrent.locks} and

    43  * {@link java.util.concurrent.atomic} packages.

    44  *

    45  * <h2>Executors</h2>

    46  *

    47  * <b>Interfaces.</b>

    48  *

    49  * {@link java.util.concurrent.Executor} is a simple standardized

    50  * interface for defining custom thread-like subsystems, including

    51  * thread pools, asynchronous IO, and lightweight task frameworks.

    52  * Depending on which concrete Executor class is being used, tasks may

    53  * execute in a newly created thread, an existing task-execution thread,

    54  * or the thread calling {@link java.util.concurrent.Executor#execute

    55  * execute}, and may execute sequentially or concurrently.

    56  *

    57  * {@link java.util.concurrent.ExecutorService} provides a more

    58  * complete asynchronous task execution framework.  An

    59  * ExecutorService manages queuing and scheduling of tasks,

    60  * and allows controlled shutdown.

    61  *

    62  * The {@link java.util.concurrent.ScheduledExecutorService}

    63  * subinterface and associated interfaces add support for

    64  * delayed and periodic task execution.  ExecutorServices

    65  * provide methods arranging asynchronous execution of any

    66  * function expressed as {@link java.util.concurrent.Callable},

    67  * the result-bearing analog of {@link java.lang.Runnable}.

    68  *

    69  * A {@link java.util.concurrent.Future} returns the results of

    70  * a function, allows determination of whether execution has

    71  * completed, and provides a means to cancel execution.

    72  *

    73  * A {@link java.util.concurrent.RunnableFuture} is a {@code Future}

    74  * that possesses a {@code run} method that upon execution,

    75  * sets its results.

    76  *

    77  * <p>

    78  *

    79  * <b>Implementations.</b>

    80  *

    81  * Classes {@link java.util.concurrent.ThreadPoolExecutor} and

    82  * {@link java.util.concurrent.ScheduledThreadPoolExecutor}

    83  * provide tunable, flexible thread pools.

    84  *

    85  * The {@link java.util.concurrent.Executors} class provides

    86  * factory methods for the most common kinds and configurations

    87  * of Executors, as well as a few utility methods for using

    88  * them.  Other utilities based on {@code Executors} include the

    89  * concrete class {@link java.util.concurrent.FutureTask}

    90  * providing a common extensible implementation of Futures, and

    91  * {@link java.util.concurrent.ExecutorCompletionService}, that

    92  * assists in coordinating the processing of groups of

    93  * asynchronous tasks.

    94  *

    95  * <h2>Queues</h2>

    96  *

    97  * The {@link java.util.concurrent.ConcurrentLinkedQueue} class

    98  * supplies an efficient scalable thread-safe non-blocking FIFO

    99  * queue.

   100  *

   101  * <p>Five implementations in {@code java.util.concurrent} support

   102  * the extended {@link java.util.concurrent.BlockingQueue}

   103  * interface, that defines blocking versions of put and take:

   104  * {@link java.util.concurrent.LinkedBlockingQueue},

   105  * {@link java.util.concurrent.ArrayBlockingQueue},

   106  * {@link java.util.concurrent.SynchronousQueue},

   107  * {@link java.util.concurrent.PriorityBlockingQueue}, and

   108  * {@link java.util.concurrent.DelayQueue}.

   109  * The different classes cover the most common usage contexts

   110  * for producer-consumer, messaging, parallel tasking, and

   111  * related concurrent designs.

   112  *

   113  * <p>The {@link java.util.concurrent.BlockingDeque} interface

   114  * extends {@code BlockingQueue} to support both FIFO and LIFO

   115  * (stack-based) operations.

   116  * Class {@link java.util.concurrent.LinkedBlockingDeque}

   117  * provides an implementation.

   118  *

   119  * <h2>Timing</h2>

   120  *

   121  * The {@link java.util.concurrent.TimeUnit} class provides

   122  * multiple granularities (including nanoseconds) for

   123  * specifying and controlling time-out based operations.  Most

   124  * classes in the package contain operations based on time-outs

   125  * in addition to indefinite waits.  In all cases that

   126  * time-outs are used, the time-out specifies the minimum time

   127  * that the method should wait before indicating that it

   128  * timed-out.  Implementations make a "best effort"

   129  * to detect time-outs as soon as possible after they occur.

   130  * However, an indefinite amount of time may elapse between a

   131  * time-out being detected and a thread actually executing

   132  * again after that time-out.  All methods that accept timeout

   133  * parameters treat values less than or equal to zero to mean

   134  * not to wait at all.  To wait "forever", you can use a value

   135  * of {@code Long.MAX_VALUE}.

   136  *

   137  * <h2>Synchronizers</h2>

   138  *

   139  * Four classes aid common special-purpose synchronization idioms.

   140  * {@link java.util.concurrent.Semaphore} is a classic concurrency tool.

   141  * {@link java.util.concurrent.CountDownLatch} is a very simple yet very

   142  * common utility for blocking until a given number of signals, events,

   143  * or conditions hold.  A {@link java.util.concurrent.CyclicBarrier} is a

   144  * resettable multiway synchronization point useful in some styles of

   145  * parallel programming.  An {@link java.util.concurrent.Exchanger} allows

   146  * two threads to exchange objects at a rendezvous point, and is useful

   147  * in several pipeline designs.

   148  *

   149  * <h2>Concurrent Collections</h2>

   150  *

   151  * Besides Queues, this package supplies Collection implementations

   152  * designed for use in multithreaded contexts:

   153  * {@link java.util.concurrent.ConcurrentHashMap},

   154  * {@link java.util.concurrent.ConcurrentSkipListMap},

   155  * {@link java.util.concurrent.ConcurrentSkipListSet},

   156  * {@link java.util.concurrent.CopyOnWriteArrayList}, and

   157  * {@link java.util.concurrent.CopyOnWriteArraySet}.

   158  * When many threads are expected to access a given collection, a

   159  * {@code ConcurrentHashMap} is normally preferable to a synchronized

   160  * {@code HashMap}, and a {@code ConcurrentSkipListMap} is normally

   161  * preferable to a synchronized {@code TreeMap}.

   162  * A {@code CopyOnWriteArrayList} is preferable to a synchronized

   163  * {@code ArrayList} when the expected number of reads and traversals

   164  * greatly outnumber the number of updates to a list.

   165 

   166  * <p>The "Concurrent" prefix used with some classes in this package

   167  * is a shorthand indicating several differences from similar

   168  * "synchronized" classes.  For example {@code java.util.Hashtable} and

   169  * {@code Collections.synchronizedMap(new HashMap())} are

   170  * synchronized.  But {@link

   171  * java.util.concurrent.ConcurrentHashMap} is "concurrent".  A

   172  * concurrent collection is thread-safe, but not governed by a

   173  * single exclusion lock.  In the particular case of

   174  * ConcurrentHashMap, it safely permits any number of

   175  * concurrent reads as well as a tunable number of concurrent

   176  * writes.  "Synchronized" classes can be useful when you need

   177  * to prevent all access to a collection via a single lock, at

   178  * the expense of poorer scalability.  In other cases in which

   179  * multiple threads are expected to access a common collection,

   180  * "concurrent" versions are normally preferable.  And

   181  * unsynchronized collections are preferable when either

   182  * collections are unshared, or are accessible only when

   183  * holding other locks.

   184  *

   185  * <p>Most concurrent Collection implementations (including most

   186  * Queues) also differ from the usual java.util conventions in that

   187  * their Iterators provide <em>weakly consistent</em> rather than

   188  * fast-fail traversal.  A weakly consistent iterator is thread-safe,

   189  * but does not necessarily freeze the collection while iterating, so

   190  * it may (or may not) reflect any updates since the iterator was

   191  * created.

   192  *

   193  * <h2><a name="MemoryVisibility">Memory Consistency Properties</a></h2>

   194  *

   195  * <a href="http://java.sun.com/docs/books/jls/third_edition/html/memory.html">

   196  * Chapter 17 of the Java Language Specification</a> defines the

   197  * <i>happens-before</i> relation on memory operations such as reads and

   198  * writes of shared variables.  The results of a write by one thread are

   199  * guaranteed to be visible to a read by another thread only if the write

   200  * operation <i>happens-before</i> the read operation.  The

   201  * {@code synchronized} and {@code volatile} constructs, as well as the

   202  * {@code Thread.start()} and {@code Thread.join()} methods, can form

   203  * <i>happens-before</i> relationships.  In particular:

   204  *

   205  * <ul>

   206  *   <li>Each action in a thread <i>happens-before</i> every action in that

   207  *   thread that comes later in the program's order.

   208  *

   209  *   <li>An unlock ({@code synchronized} block or method exit) of a

   210  *   monitor <i>happens-before</i> every subsequent lock ({@code synchronized}

   211  *   block or method entry) of that same monitor.  And because

   212  *   the <i>happens-before</i> relation is transitive, all actions

   213  *   of a thread prior to unlocking <i>happen-before</i> all actions

   214  *   subsequent to any thread locking that monitor.

   215  *

   216  *   <li>A write to a {@code volatile} field <i>happens-before</i> every

   217  *   subsequent read of that same field.  Writes and reads of

   218  *   {@code volatile} fields have similar memory consistency effects

   219  *   as entering and exiting monitors, but do <em>not</em> entail

   220  *   mutual exclusion locking.

   221  *

   222  *   <li>A call to {@code start} on a thread <i>happens-before</i> any

   223  *   action in the started thread.

   224  *

   225  *   <li>All actions in a thread <i>happen-before</i> any other thread

   226  *   successfully returns from a {@code join} on that thread.

   227  *

   228  * </ul>

   229  *

   230  *

   231  * The methods of all classes in {@code java.util.concurrent} and its

   232  * subpackages extend these guarantees to higher-level

   233  * synchronization.  In particular:

   234  *

   235  * <ul>

   236  *

   237  *   <li>Actions in a thread prior to placing an object into any concurrent

   238  *   collection <i>happen-before</i> actions subsequent to the access or

   239  *   removal of that element from the collection in another thread.

   240  *

   241  *   <li>Actions in a thread prior to the submission of a {@code Runnable}

   242  *   to an {@code Executor} <i>happen-before</i> its execution begins.

   243  *   Similarly for {@code Callables} submitted to an {@code ExecutorService}.

   244  *

   245  *   <li>Actions taken by the asynchronous computation represented by a

   246  *   {@code Future} <i>happen-before</i> actions subsequent to the

   247  *   retrieval of the result via {@code Future.get()} in another thread.

   248  *

   249  *   <li>Actions prior to "releasing" synchronizer methods such as

   250  *   {@code Lock.unlock}, {@code Semaphore.release}, and

   251  *   {@code CountDownLatch.countDown} <i>happen-before</i> actions

   252  *   subsequent to a successful "acquiring" method such as

   253  *   {@code Lock.lock}, {@code Semaphore.acquire},

   254  *   {@code Condition.await}, and {@code CountDownLatch.await} on the

   255  *   same synchronizer object in another thread.

   256  *

   257  *   <li>For each pair of threads that successfully exchange objects via

   258  *   an {@code Exchanger}, actions prior to the {@code exchange()}

   259  *   in each thread <i>happen-before</i> those subsequent to the

   260  *   corresponding {@code exchange()} in another thread.

   261  *

   262  *   <li>Actions prior to calling {@code CyclicBarrier.await}

   263  *   <i>happen-before</i> actions performed by the barrier action, and

   264  *   actions performed by the barrier action <i>happen-before</i> actions

   265  *   subsequent to a successful return from the corresponding {@code await}

   266  *   in other threads.

   267  *

   268  * </ul>

   269  *

   270  * @since 1.5

   271  */

   272 package java.util.concurrent;