Detailed discussion of functionality that has not been backported
is presented below.
Java 5.0 Syntax
Package java.util.concurrent exploits new language features
added to Java in release 5.0: most API classes are
generic types.
In the backport, they had to be flattened to standard, non-generic
classes. Still, programs linked against the backport should compile
with Java 5.0 (after changing package names). Nevertheless, you may
want to consider gradually switching to using generics once you make
the transition to Java 5.0, since it gives better compile-time
type checking.
In Condition
Method long awaitNanos(long nanosTimeout) is not supported, since the
emulation cannot reliably report remaining times with nanosecond
precision. Thus, it probably would be too dangerous to leave the
emulated method in the Condition interface. However, the method is
still available, for those who know what they are doing,
in the util.concurrent.helpers.Utils class.
In ReentrantLock
The following monitoring methods are not supported: boolean
hasWaiters(Condition), int getWaitQueueLength(Condition), Collection
getWaitingThreads(Condition).
the following monitoring methods are supported only for fair locks:
boolean hasQueuedThreads(), int getQueueLength(), Collection
getQueuedThreads(), boolean isQueued().
In ReentrantReadWriteLock
The current backport implementation is based on dl.util.concurrent class
ReentrantWriterPreferenceReadWriteLock, and thus slightly departs
from java.util.concurrent that does not specify acquisition order but
allows to enable/disable fairness. The backport implementation does not
have a single-parameter constructor allowing to specify fairness policy;
it always behaves like writer-preference lock with no fairness guarantees.
Because of these characteristics, this class is compliant with JSR 166
specification of non-fair reentrant read-write locks, while the exact
semantics of fair locks are not supported (and the appropriate
constructor is thus not provided).
Also, the following instrumentation and status methods are not
supported: Collection getQueuedWriterThreads(), Collection
getQueuedReaderThreads(), boolean hasQueuedThreads(), boolean
hasQueuedThread(Thread), Collection getQueuedThreads(), boolean
hasWaiters(Condition), int getWaitQueueLength(Condition), Collection
getWaitingThreads(Condition).
In Semaphore
Atomic multi-acquires: tryAcquire(int permits) and tryAcquire(int
permits, long timeout, TimeUnit unit) are not supported.
Platform-level functionality
To emulate System.nanoTime(), the method
nanoTime()
is provided in the class
dl.util.concurrent.helpers.Utils. On Java 1.4.2, it attempts to use
high-precision timer via sun.misc.Perf (thanks to Craig Mattocks
for suggesting this). On older Java platforms, or when sun.misc.Perf
is not supported, it falls back to System.currentTimeMillis().
Class ThreadHelpers
(added in 1.0_01) is provided to emulate certain aspects of Thread.UncaughtExceptionHandler.
Note on nanosecond precision timing
The backport strives to honor nanosecond timeouts, if such are requested,
by using two-parameter variant of Object.wait(). Note, however, that most
Java platforms before 5.0 will round up the timeout to full milliseconds
anyway.
Low-level concurrency classes
The following classes are not supported:
LockSupport, AbstractQueuedSynchronizer.
Rationale: on Java 5.0, these classes depend on explicit
JVM support, delegating to low-level OS concurrency primitives. There seems
to be no simple way of emulating them without introducing prohibitive
performance overhead. (If you think they should be present in the backport
anyway, let me know).
Atomic utilities
The following "atomic" utilities are not supported:
Atomic[Integer,Long,Reference]FieldUpdater.
Collections
JSR 166 introduces a few improvements to core collection classes, such as
Tree[Map,Set], AbstractMap, LinkedList, and Collections. For instance,
LinkedList now implements Deque, and TreeSet is now navigable. I have been
hesitant to include these classes in the backport, mainly because of the
fear of breaking compile-time backward compatibility. Namely, ambiguities
would arise from importing both java.util.* and ..backport.java.util.*.
However, I am having second thoughts on this, since navigable sets are
actually pretty useful. Opinions in this matter are greatly appreciated.
The following concurrent collection classes are not yet supported:
ConcurrentLinkedQueue, ConcurrentSkipList[Map,Set]. They will most likely be
added in future releases.