Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## edu.emory.mathcs.util.concurrent
Class ReentrantNamedLock

    java.lang.Object
      edu.emory.mathcs.util.concurrent.ReentrantNamedLock

All Implemented Interfaces:
  Lock

public class ReentrantNamedLock
extends java.lang.Object
implements Lock

Implements a reentrant named lock that can be shared between different parts of the application without sharing the lock object, by using a common name.

Author:
  Dawid Kurzyniec

Constructor Summary
`ReentrantNamedLock(java.lang.Object name)` Create a new ReentrantRemoteLock instance.

Method Summary
`boolean` | `equals(java.lang.Object other)` Two named locks are equal if their names are equal.
`int` | `hashCode()`
`void` | `lock()` Acquires the lock. If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired. Implementation Considerations A implementation may be able to detect erroneous use of the lock, such as an invocation that would cause deadlock, and may throw an (unchecked) exception in such circumstances. The circumstances and the exception type must be documented by that implementation.
`void` | `lockInterruptibly()` Acquires the lock unless the current thread is interrupted. Acquires the lock if it is available and returns immediately. If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens: The lock is acquired by the current thread; or Some other thread interrupts the current thread, and interruption of lock acquisition is supported. If the current thread: has its interrupted status set on entry to this method; or is interrupted while acquiring the lock, and interruption of lock acquisition is supported, then `InterruptedException` is thrown and the current thread's interrupted status is cleared. Implementation Considerations The ability to interrupt a lock acquisition in some implementations may not be possible, and if possible may be an expensive operation. The programmer should be aware that this may be the case. An implementation should document when this is the case. An implementation can favor responding to an interrupt over normal method return. A implementation may be able to detect erroneous use of the lock, such as an invocation that would cause deadlock, and may throw an (unchecked) exception in such circumstances. The circumstances and the exception type must be documented by that implementation.
`Condition` | `newCondition()` Returns a new `Condition` instance that is bound to this instance. Before waiting on the condition the lock must be held by the current thread. A call to `Condition.await()` will atomically release the lock before waiting and re-acquire the lock before the wait returns. Implementation Considerations The exact operation of the `Condition` instance depends on the implementation and must be documented by that implementation.
`boolean` | `tryLock()` Acquires the lock only if it is free at the time of invocation. Acquires the lock if it is available and returns immediately with the value . If the lock is not available then this method will return immediately with the value . A typical usage idiom for this method would be:
          Lock lock = ...;
          if (lock.tryLock()) {
              try {
                  // manipulate protected state
              } finally {
                  lock.unlock();
              }
          } else {
              // perform alternative actions
          }
This usage ensures that the lock is unlocked if it was acquired, and doesn't try to unlock if the lock was not acquired.
`boolean` | `tryLock(long timeout, TimeUnit unit)` Acquires the lock if it is free within the given waiting time and the current thread has not been interrupted. If the lock is available this method returns immediately with the value . If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens: The lock is acquired by the current thread; or Some other thread interrupts the current thread, and interruption of lock acquisition is supported; or The specified waiting time elapses If the lock is acquired then the value is returned. If the current thread: has its interrupted status set on entry to this method; or is interrupted while acquiring the lock, and interruption of lock acquisition is supported, then `InterruptedException` is thrown and the current thread's interrupted status is cleared. If the specified waiting time elapses then the value is returned. If the time is less than or equal to zero, the method will not wait at all. Implementation Considerations The ability to interrupt a lock acquisition in some implementations may not be possible, and if possible may be an expensive operation. The programmer should be aware that this may be the case. An implementation should document when this is the case. An implementation can favor responding to an interrupt over normal method return, or reporting a timeout. A implementation may be able to detect erroneous use of the lock, such as an invocation that would cause deadlock, and may throw an (unchecked) exception in such circumstances. The circumstances and the exception type must be documented by that implementation.
`void` | `unlock()` Releases the lock. Implementation Considerations A implementation will usually impose restrictions on which thread can release a lock (typically only the holder of the lock can release it) and may throw an (unchecked) exception if the restriction is violated. Any restrictions and the exception type must be documented by that implementation.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### ReentrantNamedLock

    public ReentrantNamedLock(java.lang.Object name)

  Create a new ReentrantRemoteLock instance.

Method Detail

### lock

    public void lock()

  Acquires the lock.

  If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired.

  Implementation Considerations

  A implementation may be able to detect erroneous use of the lock, such as an invocation that would cause deadlock, and may throw an (unchecked) exception in such circumstances. The circumstances and the exception type must be documented by that implementation.

  Specified by:
    `lock` in interface `Lock`

### tryLock

    public boolean tryLock()

  Acquires the lock only if it is free at the time of invocation.

  Acquires the lock if it is available and returns immediately with the value . If the lock is not available then this method will return immediately with the value .

  A typical usage idiom for this method would be:

            Lock lock = ...;
            if (lock.tryLock()) {
                try {
                    // manipulate protected state
                } finally {
                    lock.unlock();
                }
            } else {
                // perform alternative actions
            }

  This usage ensures that the lock is unlocked if it was acquired, and doesn't try to unlock if the lock was not acquired.

  Specified by:
    `tryLock` in interface `Lock`
  Returns:
    if the lock was acquired and otherwise

### lockInterruptibly

    public void lockInterruptibly()
                           throws java.lang.InterruptedException

  Acquires the lock unless the current thread is interrupted.

  Acquires the lock if it is available and returns immediately.

  If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens:

  - The lock is acquired by the current thread; or
  - Some other thread interrupts the current thread, and interruption of lock acquisition is supported.

  If the current thread:

  - has its interrupted status set on entry to this method; or
  - is interrupted while acquiring the lock, and interruption of lock acquisition is supported,
  then `InterruptedException` is thrown and the current thread's interrupted status is cleared.

  Implementation Considerations

  The ability to interrupt a lock acquisition in some implementations may not be possible, and if possible may be an expensive operation. The programmer should be aware that this may be the case. An implementation should document when this is the case.

  An implementation can favor responding to an interrupt over normal method return.

  A implementation may be able to detect erroneous use of the lock, such as an invocation that would cause deadlock, and may throw an (unchecked) exception in such circumstances. The circumstances and the exception type must be documented by that implementation.

  Specified by:
    `lockInterruptibly` in interface `Lock`
  Throws:
    `java.lang.InterruptedException` - if the current thread is interrupted while acquiring the lock (and interruption of lock acquisition is supported).

### tryLock

    public boolean tryLock(long timeout,
                           TimeUnit unit)
                    throws java.lang.InterruptedException

  Acquires the lock if it is free within the given waiting time and the current thread has not been interrupted.

  If the lock is available this method returns immediately with the value . If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:

  - The lock is acquired by the current thread; or
  - Some other thread interrupts the current thread, and interruption of lock acquisition is supported; or
  - The specified waiting time elapses

  If the lock is acquired then the value is returned.

  If the current thread:

  - has its interrupted status set on entry to this method; or
  - is interrupted while acquiring the lock, and interruption of lock acquisition is supported,
  then `InterruptedException` is thrown and the current thread's interrupted status is cleared.

  If the specified waiting time elapses then the value is returned. If the time is less than or equal to zero, the method will not wait at all.

  Implementation Considerations

  The ability to interrupt a lock acquisition in some implementations may not be possible, and if possible may be an expensive operation. The programmer should be aware that this may be the case. An implementation should document when this is the case.

  An implementation can favor responding to an interrupt over normal method return, or reporting a timeout.

  A implementation may be able to detect erroneous use of the lock, such as an invocation that would cause deadlock, and may throw an (unchecked) exception in such circumstances. The circumstances and the exception type must be documented by that implementation.

  Specified by:
    `tryLock` in interface `Lock`
  Parameters:
    `timeout` - the maximum time to wait for the lock
    `unit` - the time unit of the argument
  Returns:
    if the lock was acquired and if the waiting time elapsed before the lock was acquired
  Throws:
    `java.lang.InterruptedException` - if the current thread is interrupted while acquiring the lock (and interruption of lock acquisition is supported)

### unlock

    public void unlock()

  Releases the lock.

  Implementation Considerations

  A implementation will usually impose restrictions on which thread can release a lock (typically only the holder of the lock can release it) and may throw an (unchecked) exception if the restriction is violated. Any restrictions and the exception type must be documented by that implementation.

  Specified by:
    `unlock` in interface `Lock`

### newCondition

    public Condition newCondition()

  Returns a new `Condition` instance that is bound to this instance.

  Before waiting on the condition the lock must be held by the current thread. A call to `Condition.await()` will atomically release the lock before waiting and re-acquire the lock before the wait returns.

  Implementation Considerations

  The exact operation of the `Condition` instance depends on the implementation and must be documented by that implementation.

  Specified by:
    `newCondition` in interface `Lock`
  Returns:
    A new `Condition` instance for this instance

### hashCode

    public int hashCode()

### equals

    public boolean equals(java.lang.Object other)

  Two named locks are equal if their names are equal.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD