E
- The Enum type representing the explicit lock ordering.@Beta public static final class CycleDetectingLockFactory.WithExplicitOrdering<E extends Enum<E>> extends CycleDetectingLockFactory
A CycleDetectingLockFactory.WithExplicitOrdering
provides the
additional enforcement of an application-specified ordering of lock
acquisitions. The application defines the allowed ordering with an
Enum
whose values each correspond to a lock type. The order in
which the values are declared dictates the allowed order of lock
acquisition. In other words, locks corresponding to smaller values of
Enum.ordinal()
should only be acquired before locks with larger
ordinals. Example:
enum MyLockOrder {
FIRST, SECOND, THIRD;
}
CycleDetectingLockFactory.WithExplicitOrdering<MyLockOrder> factory =
CycleDetectingLockFactory.newInstanceWithExplicitOrdering(Policies.THROW);
Lock lock1 = factory.newReentrantLock(MyLockOrder.FIRST);
Lock lock2 = factory.newReentrantLock(MyLockOrder.SECOND);
Lock lock3 = factory.newReentrantLock(MyLockOrder.THIRD);
lock1.lock();
lock3.lock();
lock2.lock(); // will throw an IllegalStateException
As with all locks created by instances of CycleDetectingLockFactory
explicitly ordered locks participate in general cycle detection with all
other cycle detecting locks, and a lock's behavior when detecting a cyclic
lock acquisition is defined by the Policy
of the factory that
created it.
Note, however, that although multiple locks can be created for a given Enum value, whether it be through separate factory instances or through multiple calls to the same factory, attempting to acquire multiple locks with the same Enum value (within the same thread) will result in an IllegalStateException regardless of the factory's policy. For example:
CycleDetectingLockFactory.WithExplicitOrdering<MyLockOrder> factory1 =
CycleDetectingLockFactory.newInstanceWithExplicitOrdering(...);
CycleDetectingLockFactory.WithExplicitOrdering<MyLockOrder> factory2 =
CycleDetectingLockFactory.newInstanceWithExplicitOrdering(...);
Lock lockA = factory1.newReentrantLock(MyLockOrder.FIRST);
Lock lockB = factory1.newReentrantLock(MyLockOrder.FIRST);
Lock lockC = factory2.newReentrantLock(MyLockOrder.FIRST);
lockA.lock();
lockB.lock(); // will throw an IllegalStateException
lockC.lock(); // will throw an IllegalStateException
lockA.lock(); // reentrant acquisition is okay
It is the responsibility of the application to ensure that multiple lock instances with the same rank are never acquired in the same thread.
CycleDetectingLockFactory.Policies, CycleDetectingLockFactory.Policy, CycleDetectingLockFactory.PotentialDeadlockException, CycleDetectingLockFactory.WithExplicitOrdering<E extends Enum<E>>
Modifier and Type | Method and Description |
---|---|
ReentrantLock |
newReentrantLock(E rank)
Equivalent to
newReentrantLock(rank, false) . |
ReentrantLock |
newReentrantLock(E rank,
boolean fair)
Creates a
ReentrantLock with the given fairness policy and rank. |
ReentrantReadWriteLock |
newReentrantReadWriteLock(E rank)
Equivalent to
newReentrantReadWriteLock(rank, false) . |
ReentrantReadWriteLock |
newReentrantReadWriteLock(E rank,
boolean fair)
Creates a
ReentrantReadWriteLock with the given fairness policy
and rank. |
newInstance, newInstanceWithExplicitOrdering, newReentrantLock, newReentrantLock, newReentrantReadWriteLock, newReentrantReadWriteLock
public ReentrantLock newReentrantLock(E rank)
newReentrantLock(rank, false)
.public ReentrantLock newReentrantLock(E rank, boolean fair)
ReentrantLock
with the given fairness policy and rank.
The values returned by Enum.getDeclaringClass()
and
Enum.name()
are used to describe the lock in warning or
exception output.IllegalStateException
- If the factory has already created a
Lock
with the specified rank.public ReentrantReadWriteLock newReentrantReadWriteLock(E rank)
newReentrantReadWriteLock(rank, false)
.public ReentrantReadWriteLock newReentrantReadWriteLock(E rank, boolean fair)
ReentrantReadWriteLock
with the given fairness policy
and rank. The values returned by Enum.getDeclaringClass()
and
Enum.name()
are used to describe the lock in warning or exception
output.IllegalStateException
- If the factory has already created a
Lock
with the specified rank.Copyright © 2010-2013. All Rights Reserved.