1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/util/concurrent/package-info.java Sat Mar 19 10:46:31 2016 +0100
1.3 @@ -0,0 +1,300 @@
1.4 +/*
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.6 + *
1.7 + * This code is free software; you can redistribute it and/or modify it
1.8 + * under the terms of the GNU General Public License version 2 only, as
1.9 + * published by the Free Software Foundation. Oracle designates this
1.10 + * particular file as subject to the "Classpath" exception as provided
1.11 + * by Oracle in the LICENSE file that accompanied this code.
1.12 + *
1.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.16 + * version 2 for more details (a copy is included in the LICENSE file that
1.17 + * accompanied this code).
1.18 + *
1.19 + * You should have received a copy of the GNU General Public License version
1.20 + * 2 along with this work; if not, write to the Free Software Foundation,
1.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.22 + *
1.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.24 + * or visit www.oracle.com if you need additional information or have any
1.25 + * questions.
1.26 + */
1.27 +
1.28 +/*
1.29 + * This file is available under and governed by the GNU General Public
1.30 + * License version 2 only, as published by the Free Software Foundation.
1.31 + * However, the following notice accompanied the original version of this
1.32 + * file:
1.33 + *
1.34 + * Written by Doug Lea with assistance from members of JCP JSR-166
1.35 + * Expert Group and released to the public domain, as explained at
1.36 + * http://creativecommons.org/publicdomain/zero/1.0/
1.37 + */
1.38 +
1.39 +/**
1.40 + * Utility classes commonly useful in concurrent programming. This
1.41 + * package includes a few small standardized extensible frameworks, as
1.42 + * well as some classes that provide useful functionality and are
1.43 + * otherwise tedious or difficult to implement. Here are brief
1.44 + * descriptions of the main components. See also the
1.45 + * {@link java.util.concurrent.locks} and
1.46 + * {@link java.util.concurrent.atomic} packages.
1.47 + *
1.48 + * <h2>Executors</h2>
1.49 + *
1.50 + * <b>Interfaces.</b>
1.51 + *
1.52 + * {@link java.util.concurrent.Executor} is a simple standardized
1.53 + * interface for defining custom thread-like subsystems, including
1.54 + * thread pools, asynchronous IO, and lightweight task frameworks.
1.55 + * Depending on which concrete Executor class is being used, tasks may
1.56 + * execute in a newly created thread, an existing task-execution thread,
1.57 + * or the thread calling {@link java.util.concurrent.Executor#execute
1.58 + * execute}, and may execute sequentially or concurrently.
1.59 + *
1.60 + * {@link java.util.concurrent.ExecutorService} provides a more
1.61 + * complete asynchronous task execution framework. An
1.62 + * ExecutorService manages queuing and scheduling of tasks,
1.63 + * and allows controlled shutdown.
1.64 + *
1.65 + * The {@link java.util.concurrent.ScheduledExecutorService}
1.66 + * subinterface and associated interfaces add support for
1.67 + * delayed and periodic task execution. ExecutorServices
1.68 + * provide methods arranging asynchronous execution of any
1.69 + * function expressed as {@link java.util.concurrent.Callable},
1.70 + * the result-bearing analog of {@link java.lang.Runnable}.
1.71 + *
1.72 + * A {@link java.util.concurrent.Future} returns the results of
1.73 + * a function, allows determination of whether execution has
1.74 + * completed, and provides a means to cancel execution.
1.75 + *
1.76 + * A {@link java.util.concurrent.RunnableFuture} is a {@code Future}
1.77 + * that possesses a {@code run} method that upon execution,
1.78 + * sets its results.
1.79 + *
1.80 + * <p>
1.81 + *
1.82 + * <b>Implementations.</b>
1.83 + *
1.84 + * Classes {@link java.util.concurrent.ThreadPoolExecutor} and
1.85 + * {@link java.util.concurrent.ScheduledThreadPoolExecutor}
1.86 + * provide tunable, flexible thread pools.
1.87 + *
1.88 + * The {@link java.util.concurrent.Executors} class provides
1.89 + * factory methods for the most common kinds and configurations
1.90 + * of Executors, as well as a few utility methods for using
1.91 + * them. Other utilities based on {@code Executors} include the
1.92 + * concrete class {@link java.util.concurrent.FutureTask}
1.93 + * providing a common extensible implementation of Futures, and
1.94 + * {@link java.util.concurrent.ExecutorCompletionService}, that
1.95 + * assists in coordinating the processing of groups of
1.96 + * asynchronous tasks.
1.97 + *
1.98 + * <p>Class {@link java.util.concurrent.ForkJoinPool} provides an
1.99 + * Executor primarily designed for processing instances of {@link
1.100 + * java.util.concurrent.ForkJoinTask} and its subclasses. These
1.101 + * classes employ a work-stealing scheduler that attains high
1.102 + * throughput for tasks conforming to restrictions that often hold in
1.103 + * computation-intensive parallel processing.
1.104 + *
1.105 + * <h2>Queues</h2>
1.106 + *
1.107 + * The {@link java.util.concurrent.ConcurrentLinkedQueue} class
1.108 + * supplies an efficient scalable thread-safe non-blocking FIFO
1.109 + * queue.
1.110 + *
1.111 + * <p>Five implementations in {@code java.util.concurrent} support
1.112 + * the extended {@link java.util.concurrent.BlockingQueue}
1.113 + * interface, that defines blocking versions of put and take:
1.114 + * {@link java.util.concurrent.LinkedBlockingQueue},
1.115 + * {@link java.util.concurrent.ArrayBlockingQueue},
1.116 + * {@link java.util.concurrent.SynchronousQueue},
1.117 + * {@link java.util.concurrent.PriorityBlockingQueue}, and
1.118 + * {@link java.util.concurrent.DelayQueue}.
1.119 + * The different classes cover the most common usage contexts
1.120 + * for producer-consumer, messaging, parallel tasking, and
1.121 + * related concurrent designs.
1.122 + *
1.123 + * <p> Extended interface {@link java.util.concurrent.TransferQueue},
1.124 + * and implementation {@link java.util.concurrent.LinkedTransferQueue}
1.125 + * introduce a synchronous {@code transfer} method (along with related
1.126 + * features) in which a producer may optionally block awaiting its
1.127 + * consumer.
1.128 + *
1.129 + * <p>The {@link java.util.concurrent.BlockingDeque} interface
1.130 + * extends {@code BlockingQueue} to support both FIFO and LIFO
1.131 + * (stack-based) operations.
1.132 + * Class {@link java.util.concurrent.LinkedBlockingDeque}
1.133 + * provides an implementation.
1.134 + *
1.135 + * <h2>Timing</h2>
1.136 + *
1.137 + * The {@link java.util.concurrent.TimeUnit} class provides
1.138 + * multiple granularities (including nanoseconds) for
1.139 + * specifying and controlling time-out based operations. Most
1.140 + * classes in the package contain operations based on time-outs
1.141 + * in addition to indefinite waits. In all cases that
1.142 + * time-outs are used, the time-out specifies the minimum time
1.143 + * that the method should wait before indicating that it
1.144 + * timed-out. Implementations make a "best effort"
1.145 + * to detect time-outs as soon as possible after they occur.
1.146 + * However, an indefinite amount of time may elapse between a
1.147 + * time-out being detected and a thread actually executing
1.148 + * again after that time-out. All methods that accept timeout
1.149 + * parameters treat values less than or equal to zero to mean
1.150 + * not to wait at all. To wait "forever", you can use a value
1.151 + * of {@code Long.MAX_VALUE}.
1.152 + *
1.153 + * <h2>Synchronizers</h2>
1.154 + *
1.155 + * Five classes aid common special-purpose synchronization idioms.
1.156 + * <ul>
1.157 + *
1.158 + * <li>{@link java.util.concurrent.Semaphore} is a classic concurrency tool.
1.159 + *
1.160 + * <li>{@link java.util.concurrent.CountDownLatch} is a very simple yet
1.161 + * very common utility for blocking until a given number of signals,
1.162 + * events, or conditions hold.
1.163 + *
1.164 + * <li>A {@link java.util.concurrent.CyclicBarrier} is a resettable
1.165 + * multiway synchronization point useful in some styles of parallel
1.166 + * programming.
1.167 + *
1.168 + * <li>A {@link java.util.concurrent.Phaser} provides
1.169 + * a more flexible form of barrier that may be used to control phased
1.170 + * computation among multiple threads.
1.171 + *
1.172 + * <li>An {@link java.util.concurrent.Exchanger} allows two threads to
1.173 + * exchange objects at a rendezvous point, and is useful in several
1.174 + * pipeline designs.
1.175 + *
1.176 + * </ul>
1.177 + *
1.178 + * <h2>Concurrent Collections</h2>
1.179 + *
1.180 + * Besides Queues, this package supplies Collection implementations
1.181 + * designed for use in multithreaded contexts:
1.182 + * {@link java.util.concurrent.ConcurrentHashMap},
1.183 + * {@link java.util.concurrent.ConcurrentSkipListMap},
1.184 + * {@link java.util.concurrent.ConcurrentSkipListSet},
1.185 + * {@link java.util.concurrent.CopyOnWriteArrayList}, and
1.186 + * {@link java.util.concurrent.CopyOnWriteArraySet}.
1.187 + * When many threads are expected to access a given collection, a
1.188 + * {@code ConcurrentHashMap} is normally preferable to a synchronized
1.189 + * {@code HashMap}, and a {@code ConcurrentSkipListMap} is normally
1.190 + * preferable to a synchronized {@code TreeMap}.
1.191 + * A {@code CopyOnWriteArrayList} is preferable to a synchronized
1.192 + * {@code ArrayList} when the expected number of reads and traversals
1.193 + * greatly outnumber the number of updates to a list.
1.194 +
1.195 + * <p>The "Concurrent" prefix used with some classes in this package
1.196 + * is a shorthand indicating several differences from similar
1.197 + * "synchronized" classes. For example {@code java.util.Hashtable} and
1.198 + * {@code Collections.synchronizedMap(new HashMap())} are
1.199 + * synchronized. But {@link
1.200 + * java.util.concurrent.ConcurrentHashMap} is "concurrent". A
1.201 + * concurrent collection is thread-safe, but not governed by a
1.202 + * single exclusion lock. In the particular case of
1.203 + * ConcurrentHashMap, it safely permits any number of
1.204 + * concurrent reads as well as a tunable number of concurrent
1.205 + * writes. "Synchronized" classes can be useful when you need
1.206 + * to prevent all access to a collection via a single lock, at
1.207 + * the expense of poorer scalability. In other cases in which
1.208 + * multiple threads are expected to access a common collection,
1.209 + * "concurrent" versions are normally preferable. And
1.210 + * unsynchronized collections are preferable when either
1.211 + * collections are unshared, or are accessible only when
1.212 + * holding other locks.
1.213 + *
1.214 + * <p>Most concurrent Collection implementations (including most
1.215 + * Queues) also differ from the usual java.util conventions in that
1.216 + * their Iterators provide <em>weakly consistent</em> rather than
1.217 + * fast-fail traversal. A weakly consistent iterator is thread-safe,
1.218 + * but does not necessarily freeze the collection while iterating, so
1.219 + * it may (or may not) reflect any updates since the iterator was
1.220 + * created.
1.221 + *
1.222 + * <h2><a name="MemoryVisibility">Memory Consistency Properties</a></h2>
1.223 + *
1.224 + * Chapter 17 of
1.225 + * <cite>The Java™ Language Specification</cite>
1.226 + * defines the
1.227 + * <i>happens-before</i> relation on memory operations such as reads and
1.228 + * writes of shared variables. The results of a write by one thread are
1.229 + * guaranteed to be visible to a read by another thread only if the write
1.230 + * operation <i>happens-before</i> the read operation. The
1.231 + * {@code synchronized} and {@code volatile} constructs, as well as the
1.232 + * {@code Thread.start()} and {@code Thread.join()} methods, can form
1.233 + * <i>happens-before</i> relationships. In particular:
1.234 + *
1.235 + * <ul>
1.236 + * <li>Each action in a thread <i>happens-before</i> every action in that
1.237 + * thread that comes later in the program's order.
1.238 + *
1.239 + * <li>An unlock ({@code synchronized} block or method exit) of a
1.240 + * monitor <i>happens-before</i> every subsequent lock ({@code synchronized}
1.241 + * block or method entry) of that same monitor. And because
1.242 + * the <i>happens-before</i> relation is transitive, all actions
1.243 + * of a thread prior to unlocking <i>happen-before</i> all actions
1.244 + * subsequent to any thread locking that monitor.
1.245 + *
1.246 + * <li>A write to a {@code volatile} field <i>happens-before</i> every
1.247 + * subsequent read of that same field. Writes and reads of
1.248 + * {@code volatile} fields have similar memory consistency effects
1.249 + * as entering and exiting monitors, but do <em>not</em> entail
1.250 + * mutual exclusion locking.
1.251 + *
1.252 + * <li>A call to {@code start} on a thread <i>happens-before</i> any
1.253 + * action in the started thread.
1.254 + *
1.255 + * <li>All actions in a thread <i>happen-before</i> any other thread
1.256 + * successfully returns from a {@code join} on that thread.
1.257 + *
1.258 + * </ul>
1.259 + *
1.260 + *
1.261 + * The methods of all classes in {@code java.util.concurrent} and its
1.262 + * subpackages extend these guarantees to higher-level
1.263 + * synchronization. In particular:
1.264 + *
1.265 + * <ul>
1.266 + *
1.267 + * <li>Actions in a thread prior to placing an object into any concurrent
1.268 + * collection <i>happen-before</i> actions subsequent to the access or
1.269 + * removal of that element from the collection in another thread.
1.270 + *
1.271 + * <li>Actions in a thread prior to the submission of a {@code Runnable}
1.272 + * to an {@code Executor} <i>happen-before</i> its execution begins.
1.273 + * Similarly for {@code Callables} submitted to an {@code ExecutorService}.
1.274 + *
1.275 + * <li>Actions taken by the asynchronous computation represented by a
1.276 + * {@code Future} <i>happen-before</i> actions subsequent to the
1.277 + * retrieval of the result via {@code Future.get()} in another thread.
1.278 + *
1.279 + * <li>Actions prior to "releasing" synchronizer methods such as
1.280 + * {@code Lock.unlock}, {@code Semaphore.release}, and
1.281 + * {@code CountDownLatch.countDown} <i>happen-before</i> actions
1.282 + * subsequent to a successful "acquiring" method such as
1.283 + * {@code Lock.lock}, {@code Semaphore.acquire},
1.284 + * {@code Condition.await}, and {@code CountDownLatch.await} on the
1.285 + * same synchronizer object in another thread.
1.286 + *
1.287 + * <li>For each pair of threads that successfully exchange objects via
1.288 + * an {@code Exchanger}, actions prior to the {@code exchange()}
1.289 + * in each thread <i>happen-before</i> those subsequent to the
1.290 + * corresponding {@code exchange()} in another thread.
1.291 + *
1.292 + * <li>Actions prior to calling {@code CyclicBarrier.await} and
1.293 + * {@code Phaser.awaitAdvance} (as well as its variants)
1.294 + * <i>happen-before</i> actions performed by the barrier action, and
1.295 + * actions performed by the barrier action <i>happen-before</i> actions
1.296 + * subsequent to a successful return from the corresponding {@code await}
1.297 + * in other threads.
1.298 + *
1.299 + * </ul>
1.300 + *
1.301 + * @since 1.5
1.302 + */
1.303 +package java.util.concurrent;