Disclaimer - This prototype is experimental code developed as part of - JSR166 and made available to the developer community for use + JCP JSR166 and made available to the developer community for use as-is. It is not a supported product. Use it at your own risk. The specification, language and implementation are subject to change as a result of your feedback. Because these features have not yet been @@ -24,182 +24,146 @@ To join a mailing list discussing this J their inclusion in a product. -
-Package java.util.concurrent contains utility classes that are -commonly useful in concurrent programming. Like package java.util, it -includes a few small standardized extensible frameworks, as well as -some classes that provide useful functionality and are otherwise -tedious or difficult to implement. In this JSR, we have been -conservative in selecting only those APIs and implementations that are -useful enough to encourage nearly all concurrent programmers to use -routinely. JSR 166 also includes a few changes and additions in -packages outside of java.util.concurrent: java.lang, to address -uncaught exceptions, and java.util to better integrate queues. -The API covers: - -
Package java.util.concurrent contains utility classes commonly +useful in concurrent programming. Like package java.util, it includes +a few small standardized extensible frameworks, as well as some +classes that provide useful functionality and are otherwise tedious or +difficult to implement. JSR166 also includes a few changes and +additions in packages outside of java.util.concurrent: java.lang, to +address uncaught exceptions, and java.util to better integrate with +collections. Since the target release is JDK1.5, many APIs use +generics to parameterize on types. Here are brief descriptions of the +main components. -
-Here are brief descriptions and rationales of the main components. -For details see the javadocs at http://gee.cs.oswego.edu/dl/concurrent/index.html +
{@link java.util.concurrent.ExecutorService} provides a more +complete framework for executing Runnables. An ExecutorService +manages queueing and scheduling of tasks, and allows controlled +shutdown. The two primary implementations of ExecutorService are +{@link java.util.concurrent.ThreadPoolExecutor}, a highly tunable and +flexible thread pool and {@link +java.util.concurrent.ScheduledExecutor}, which adds support for +delayed and periodic task execution. These, and other Executors can +be used in conjunction with a {@link FutureTask} to asynchronously +start a potentially long-running computation and query the FutureTask +to determine if its execution has completed, or cancel it. + +
The {@link java.util.concurrent.Executors} class provides factory +methods for the most common kinds and styles of Executors, as well as +a few utilities methods for using them.
Five implementations in java.util.concurrent support the extended -BlockingQueue interface, that defines blocking versions of put and -take: LinkedBlockingQueue, ArrayBlockingQueue, SynchronousQueue, -PriorityBlockingQueue, and DelayQueue. Additionally, -java.util.concurrent.LinkedQueue supplies an efficient thread-safe -non-blocking queue. - -
Since the target release is JDK1.5, and generics are slated to be -in 1.5, Queues are parametrized on element type. (Also some others -below.) - - -
Executors provide a framework for executing Runnables. The -Executor manages queueing and scheduling of tasks, and creation and -teardown of threads. 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 execute(), and may -execute sequentially or concurrently. - -
Several concrete implementations of Executor are included in -java.util.concurrent, including ThreadPoolExecutor, a flexible thread -pool and ScheduledExecutor, which adds support for delayed and -periodic task execution. Executor can be used in conjunction with -FutureTask (which implements Runnable) to asynchronously start a -potentially long-running computation and query the FutureTask to -determine if its execution has completed. - -
The Executors class provides factory methods for all -of the types of executors provided in -java.util.concurrent. +{@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 DelayQueue}.
-The Locks class additionally supports trylock-designs using builtin -locks without needing to use Lock classes. This requires adding new -capabilities to builtin locks inside JVMs. - -
-A ReadWriteLock interface similarly defines locks that may be shared -among readers but are exclusive to writers. For this release, only a -single implementation, ReentrantReadWriteLock, is planned, since it +The {@link java.util.concurrent.Lock} interface supports locking +disciplines that differ in semantics (reentrant, fair, etc), and that +can be used in non-block-structured contexts including hand-over-hand +and lock reordering algorithms. This flexibility comes at the price of +more awkward syntax. Implementations include {@link +java.util.concurrent.ReentrantLock} and {@link +java.util.concurrent.FairReentrantLock}. + +
The {@link java.util.concurrent.Locks} class additionally supports +some common trylock-designs using builtin locks. + +
The {@link java.util.concurrent.ReadWriteLock} interface similarly +defines locks that may be shared among readers but are exclusive to +writers. Only a single implementation, {@link +java.util.concurrent.ReentrantReadWriteLock}, is provided, since it covers all standard usage contexts. But programmers may create their own implementations to cover nonstandard requirements.
-To avoid compatibility problems, the names of Condition methods need -to be different than Object versions. The downside of this is that -people can make the mistake of calling cond.notify instead of -cond.signal. However, they will get IllegalMonitorState exceptions if -they do, so they can detect the error if they ever run the code. - +The {@link java.util.concurrent.Condition} interface describes the +kinds of condition variables associated with monitors in other +concurrent languages, as well as pthreads-style condvars. Their +support reduces the need for tricky and/or inefficient solutions to +many classic concurrent problems. To avoid compatibility problems, +the names of Condition methods are different than Object versions. -
Most concurrent Collection implementations (including most Queues) +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.
Additionally, ThreadLocals will now support a means to remove a -ThreadLocal, which is needed in some thread-pool and worker-thread +
Additionally, java.lang.ThreadLocal now supports a means to remove +a ThreadLocal, which is needed in some thread-pool and worker-thread designs.