--- jsr166/src/main/intro.html 2003/06/24 14:33:52 1.4 +++ jsr166/src/main/intro.html 2004/11/21 01:40:32 1.19 @@ -1,172 +1,98 @@
--To join a mailing list discussing this JSR, go to: - http://altair.cs.oswego.edu/mailman/listinfo/concurrency-interest . - -
-
- Disclaimer - This prototype is experimental code developed as part of
- 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
- approved for addition to the Java language, there is no schedule for
- their inclusion in a product.
+This is maintenance repository of JSR166 specifications. For further
+information, go to:
+http://altair.cs.oswego.edu/mailman/listinfo/concurrency-interest.
+
+ Note: The javadocs here do not include pre-existing
+java classes (for example java.lang.Thread) that were changed
+as part of the JSR166 spec. On the other hand, the javadocs here so
+include some existing java.util Collection interfaces and classes that
+are not part of the spec, but are included because some new methods
+implement or inherit from their specifications.
- 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.
-
- {@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.
+ JSR-166 introduces package java.util.concurrent
+containing utility classes commonly useful in concurrent
+programming. Like package java.util, it includes a few small
+standardized extensible frameworks, as well as other classes that
+provide useful functionality and are otherwise tedious or difficult to
+implement.
+
+ JSR-166 focusses on breadth, providing critical functionality
+useful across a wide range of concurrent programming styles and
+applications, ranging from low-level atomic operations, to
+customizable locks and synchronization aids, to various concurrent
+data structures, to high-level execution agents including thread
+pools. This diversity reflects the range of contexts in which
+developers of concurrent programs have been found to require or desire
+support not previously available in J2SE, which also keeping the
+resulting package small; providing only functionality that has been
+found to be worthwhile to standardize.
+
+ Descriptions and brief motivations for the main components may be
+found in the associated package documentation. JSR-166 also includes
+a few changes and additions in packages outside of
+java.util.concurrent. Here are brief descriptions.
Five implementations in java.util.concurrent support the extended
-{@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 {@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.
-
- 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, java.lang.ThreadLocal now supports a means to remove
+The {@link java.lang.ThreadLocal} class now supports a means to remove
a ThreadLocal, which is needed in some thread-pool and worker-thread
designs.
+
+
Executors
-
-{@link java.util.concurrent.Executor} is a simple standardized
-interface for defining custom thread-like subsystems, including thread
-pools, asynch-IO, and lightweight task frameworks. 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. Executors also standardize ways of calling threads that
-compute functions returning results, via a {@link
-java.util.concurrent.Future}. This is supported in part by defining
-interface {@link java.util.concurrent.Callable}, the argument/result
-analog of Runnable.
-
-Queues
A basic (nonblocking) {@link java.util.Queue} interface extending
-java.util.Collection is introduced into java.util. Existing class
-java.util.LinkedList is adapted to support Queue, and a new
-non-thread-safe {@link java.util.concurrent.java.util.PriorityQueue}
-is added. The java.util.concurrent {@link
-java.util.concurrent.LinkedQueue} class supplies an efficient
-thread-safe non-blocking queue.
-
-Locks
-
-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}.
-
-Conditions
-
-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.
-
-Atomics
-
-The atomic subpackage includes a small library of classes, including
-AtomicInteger, AtomicLong, and AtomicReference that support
-compareAndSet (CAS) and related atomic operations.
+{@link java.util.Collection} is introduced into
+java.util. Existing class {@link java.util.LinkedList} is
+adapted to support Queue, and a new non-thread-safe {@link
+java.util.PriorityQueue} is added.
+
+Threads
+
+Three minor changes are introduced to the {@link java.lang.Thread}
+class:
+
+
Timing
-The {@link java.util.concurrent.TimeUnit} class provides multiple
-granularities (including nanoseconds) for both accessing time and
-performing time-out based operations.
-
-Synchronizers
-
-Five classes aid common special-purpose synchronization idioms.
-{@link java.util.concurrent.Semaphore} and {@link
-java.util.concurrent.FairSemaphore} are classic concurrency tools.
-{@link java.util.concurrent.CountDownLatch} is very simple yet very
-common utility for blocking until a single signal, event, or condition
-holds. A {@link CyclicBarrier} is a resettable multiway
-synchronization point common in some styles of parallel
-programming. An {@link java.util.concurrent.Exchanger} allows two
-threads to exchange objects at a rendezvous point.
-
-Concurrent Collections
-
-This package supplies a few Collection implementations designed for
-use in multithreaded contexts: {@link
-java.util.concurrent.ConcurrentHashMap}, {@link
-java.util.concurrent.CopyOnWriteArrayList}, and {@link
-java.util.concurrent.CopyOnWriteArraySet}.
-
-Uncaught Exception Handlers
-
-The java.lang.Thread class is modified to allow per-thread
-installation of handlers for uncaught exceptions. Ths optionally
-disassociates these handlers from ThreadGroups, which has proven to be
-too inflexible in many multithreaded programs. (Note that the
-combination of features in JSR166 make ThreadGroups even less likely
-to be used in most programs. Perhaps they will eventually be
-deprecated.)
+Method nanoTime is added to {@link java.lang.System}. It
+provides a high-precision timing facility that is distinct from and
+uncoordinated with System.currentTimeMillis.
+
+Removing ThreadLocals
-
- Doug Lea