com.bluegosling.concurrent.locks

Class HierarchicalLock.SharedLock

java.lang.Object

com.bluegosling.concurrent.locks.HierarchicalLock.SharedLock

All Implemented Interfaces:

HierarchicalLock.AcquiredLock

Enclosing class:

HierarchicalLock

public class HierarchicalLock.SharedLock
extends Object
implements HierarchicalLock.AcquiredLock

The result of acquiring a shared lock on a HierarchicalLock. This object is used to release the lock or to change it (via promotion or demotion).

Unlike other types of promotion and demotion, promoting a shared lock to its parent or demoting to one of its children will succeed, even if more than one such shared lock is held (from re-entrance).

See Also:

HierarchicalLock.sharedLock(), HierarchicalLock.sharedLockInterruptibly(), HierarchicalLock.trySharedLock(), HierarchicalLock.trySharedLock(long, TimeUnit)

Method Summary

Modifier and Type	Method and Description
HierarchicalLock.SharedLock	demoteToChild(HierarchicalLock child) Demotes this lock to a shared lock on one of its children.
HierarchicalLock.SharedLock	demoteToChildInterruptibly(HierarchicalLock child) Demotes this lock to a shared lock on one of its children, waiting interruptibly until it is available.
HierarchicalLock.ExclusiveLock	promoteToExclusive() Promotes this shared lock into an exclusive lock.
HierarchicalLock.ExclusiveLock	promoteToExclusiveInterruptibly() Promotes this shared lock into an exclusive lock, waiting interruptibly until the exclusive lock becomes available.
HierarchicalLock.SharedLock	promoteToParent() Promotes this lock to a shared lock on its parent.
HierarchicalLock.SharedLock	tryDemoteToChild(HierarchicalLock child) Tries to demote this lock to a shared lock on one of its children, returning immediately if the child lock is unavailable.
HierarchicalLock.SharedLock	tryDemoteToChild(HierarchicalLock child, long timeLimit, TimeUnit unit) Tries to demote this lock to a shared lock on one of its children, waiting for the specified amount of time before giving up.
HierarchicalLock.ExclusiveLock	tryPromoteToExclusive() Promotes this shared lock into an exclusive lock, returning immediately if the exclusive lock is unavailable.
HierarchicalLock.ExclusiveLock	tryPromoteToExclusive(long timeLimit, TimeUnit unit) Promotes this shared lock into an exclusive lock, waiting up to the given amount of time before giving up.
void	unlock() Releases the held lock.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

unlock

public void unlock()

Description copied from interface: HierarchicalLock.AcquiredLock

Releases the held lock.

Specified by:

unlock in interface HierarchicalLock.AcquiredLock

promoteToExclusive

public HierarchicalLock.ExclusiveLock promoteToExclusive()

Promotes this shared lock into an exclusive lock. This basically releases the held lock and replaces it with an exclusive lock on the same HierarchicalLock. This method will block until the exclusive lock becomes available.

Returns:

the newly acquired exclusive lock

Throws:

IllegalStateException - if this thread does not hold this lock or has already released it; or if the shared lock has been acquired by this thread more than once (in a re-entrant manner)

DeadlockException - if waiting for the exclusive lock would result in a deadlock (e.g. this thread holds a lock for which another thread is waiting, and that thread, or some other thread that directly or indirectly is waiting on it, is holding the exclusive lock)

promoteToExclusiveInterruptibly

public HierarchicalLock.ExclusiveLock promoteToExclusiveInterruptibly()
                                                               throws InterruptedException

Promotes this shared lock into an exclusive lock, waiting interruptibly until the exclusive lock becomes available. This basically releases the held lock and replaces it with an exclusive lock on the same HierarchicalLock.

Returns:

the newly acquired exclusive lock

Throws:

InterruptedException - if this thread is interrupted while waiting for the exclusive lock to become available

IllegalStateException - if this thread does not hold this lock or has already released it; or if the shared lock has been acquired by this thread more than once (in a re-entrant manner)

DeadlockException - if waiting for the exclusive lock would result in a deadlock (e.g. this thread holds a lock for which another thread is waiting, and that thread, or some other thread that directly or indirectly is waiting on it, is holding the exclusive lock)

tryPromoteToExclusive

public HierarchicalLock.ExclusiveLock tryPromoteToExclusive()

Promotes this shared lock into an exclusive lock, returning immediately if the exclusive lock is unavailable. This basically releases the held lock and replaces it with an exclusive lock on the same HierarchicalLock.

Returns:

the newly acquired exclusive lock or null if it is not available

Throws:

IllegalStateException - if this thread does not hold this lock or has already released it; or if the shared lock has been acquired by this thread more than once (in a re-entrant manner)

DeadlockException - if waiting for the exclusive lock would result in a deadlock (e.g. this thread holds a lock for which another thread is waiting, and that thread, or some other thread that directly or indirectly is waiting on it, is holding the exclusive lock)

tryPromoteToExclusive

public HierarchicalLock.ExclusiveLock tryPromoteToExclusive(long timeLimit,
                                                            TimeUnit unit)
                                                     throws InterruptedException

Promotes this shared lock into an exclusive lock, waiting up to the given amount of time before giving up. This basically releases the held lock and replaces it with an exclusive lock on the same HierarchicalLock.

Parameters:

timeLimit - the limit of time to wait for the lock

unit - the unit of the time limit

Returns:

the newly acquired exclusive lock or null if the time limit lapsed before the lock became available

Throws:

InterruptedException - if this thread is interrupted while waiting for the exclusive lock to become available

IllegalStateException - if this thread does not hold this lock or has already released it; or if the shared lock has been acquired by this thread more than once (in a re-entrant manner)

DeadlockException - if waiting for the exclusive lock would result in a deadlock (e.g. this thread holds a lock for which another thread is waiting, and that thread, or some other thread that directly or indirectly is waiting on it, is holding the exclusive lock)

demoteToChild

public HierarchicalLock.SharedLock demoteToChild(HierarchicalLock child)

Demotes this lock to a shared lock on one of its children. On success, this held lock is released and replaced with a new HierarchicalLock.SharedLock that represents the lock on the child. This method will block until the child lock is available.

Specified by:

demoteToChild in interface HierarchicalLock.AcquiredLock

Parameters:

child - the child of this lock to which this lock is demoted

Returns:

the newly acquired lock on the given child

Throws:

IllegalStateException - if this thread does not hold this lock or has already released it; or if the given lock is not actually a child of the HierarchicalLock which produced this HierarchicalLock.SharedLock

DeadlockException - if waiting for the child lock would result in a deadlock (e.g. this thread holds a lock for which another thread is waiting, and that thread, or some other thread that directly or indirectly is waiting on it, is holding the child lock)

demoteToChildInterruptibly

public HierarchicalLock.SharedLock demoteToChildInterruptibly(HierarchicalLock child)
                                                       throws InterruptedException

Demotes this lock to a shared lock on one of its children, waiting interruptibly until it is available. On success, this held lock is released and replaced with a new HierarchicalLock.SharedLock that represents the lock on the child.

Parameters:

child - the child of this lock to which this lock is demoted

Returns:

the newly acquired lock on the given child

Throws:

DeadlockException

InterruptedException - if this thread is interrupted while waiting for the child lock to become available

IllegalStateException - if this thread does not hold this lock or has already released it; or if the given lock is not actually a child of the HierarchicalLock which produced this HierarchicalLock.SharedLock

DeadlockException - if waiting for the child lock would result in a deadlock (e.g. this thread holds a lock for which another thread is waiting, and that thread, or some other thread that directly or indirectly is waiting on it, is holding the child lock)

tryDemoteToChild

public HierarchicalLock.SharedLock tryDemoteToChild(HierarchicalLock child)

Tries to demote this lock to a shared lock on one of its children, returning immediately if the child lock is unavailable. On success, this held lock is released and replaced with a new HierarchicalLock.SharedLock that represents the lock on the child.

Parameters:

child - the child of this lock to which this lock is demoted

Returns:

the newly acquired lock on the given child or null if it was not available

Throws:

DeadlockException

IllegalStateException - if this thread does not hold this lock or has already released it; or if the given lock is not actually a child of the HierarchicalLock which produced this HierarchicalLock.SharedLock

DeadlockException - if waiting for the child lock would result in a deadlock (e.g. this thread holds a lock for which another thread is waiting, and that thread, or some other thread that directly or indirectly is waiting on it, is holding the child lock)

tryDemoteToChild

public HierarchicalLock.SharedLock tryDemoteToChild(HierarchicalLock child,
                                                    long timeLimit,
                                                    TimeUnit unit)
                                             throws InterruptedException

Tries to demote this lock to a shared lock on one of its children, waiting for the specified amount of time before giving up. On success, this held lock is released and replaced with a new HierarchicalLock.SharedLock that represents the lock on the child.

Parameters:

child - the child of this lock to which this lock is demoted

timeLimit - the limit of time to wait for the lock

unit - the unit of the time limit

Returns:

the newly acquired lock on the given child or null if the time limit lapsed before the lock became available

Throws:

InterruptedException - if this thread is interrupted while waiting for the child lock to become available

IllegalStateException - if this thread does not hold this lock or has already released it; or if the given lock is not actually a child of the HierarchicalLock which produced this HierarchicalLock.SharedLock

DeadlockException - if waiting for the child lock would result in a deadlock (e.g. this thread holds a lock for which another thread is waiting, and that thread, or some other thread that directly or indirectly is waiting on it, is holding the child lock)

promoteToParent

public HierarchicalLock.SharedLock promoteToParent()

Promotes this lock to a shared lock on its parent. On success, the held lock is released and replaced with a new HierarchicalLock.SharedLock that represents the lock on the parent. This method does not need to block since all acquired locks also hold implicit shared locks on parent/ancestor locks.

Specified by:

promoteToParent in interface HierarchicalLock.AcquiredLock

Returns:

the newly acquired lock on the parent

Throws:

IllegalStateException - if this thread does not hold this lock or has already released it; or if the lock that produced this HierarchicalLock.SharedLock is a root lock and does not have a parent

DeadlockException - if waiting for the parent lock would result in a deadlock (e.g. this thread holds a lock for which another thread is waiting, and that thread, or some other thread that directly or indirectly is waiting on it, is holding the parent lock)