org.apache.ignite.internal.processors.datastructures

## Class GridCacheLockImpl

- java.lang.Object
- - org.apache.ignite.internal.processors.datastructures.GridCacheLockImpl

All Implemented Interfaces:
  Closeable, Externalizable, Serializable, AutoCloseable, Lock, IgniteLock, GridCacheLockEx, GridCacheRemovable

    public final class GridCacheLockImpl
    extends Object
    implements GridCacheLockEx, Externalizable

Cache reentrant lock implementation based on AbstractQueuedSynchronizer.

See Also:
  Serialized Form

### Constructor Summary

Constructors
Constructor and Description
`GridCacheLockImpl()` Empty constructor required by `Externalizable`.
`GridCacheLockImpl(String name, GridCacheInternalKey key, IgniteInternalCache<GridCacheInternalKey,GridCacheLockState> lockView, GridCacheContext ctx)` Constructor.

### Method Summary

Methods
`void` `close()` Removes reentrant lock.
`int` `getHoldCount()` Queries the number of holds on this lock by the current thread.
`IgniteCondition` `getOrCreateCondition(String name)` Returns a `Condition` instance for use with this `IgniteLock` instance.
`int` `getWaitQueueLength(IgniteCondition condition)` Returns an estimate of the number of threads on this node that are waiting on the given condition associated with this lock.
`boolean` `hasQueuedThread(Thread thread)` Queries whether the given thread is waiting to acquire this lock.
`boolean` `hasQueuedThreads()` Queries whether any threads on this node are waiting to acquire this lock.
`boolean` `hasWaiters(IgniteCondition condition)` Queries whether any threads on this node are waiting on the given condition associated with this lock.
`boolean` `isBroken()` Returns true if any node that owned the locked failed before releasing the lock.
`boolean` `isFailoverSafe()` Returns `true` if this lock is safe to use after node failure.
`boolean` `isFair()` Returns `true` if this lock is fair.
`boolean` `isHeldByCurrentThread()` Queries if this lock is held by the current thread.
`boolean` `isLocked()` Queries if this lock is held by any thread on any node.
`GridCacheInternalKey` `key()` Get current reentrant lock latch key.
`void` `lock()` Acquires the distributed reentrant lock.
`void` `lockInterruptibly()` Acquires the lock unless the current thread is interrupted.
`String` `name()` Name of atomic reentrant lock.
`void` `needCheckNotRemoved()`
`Condition` `newCondition()` This method is not supported in IgniteLock, Any invocation of this method will result in UnsupportedOperationException.
`void` `onNodeRemoved(UUID nodeId)` Callback to notify semaphore on topology changes.
`boolean` `onRemoved()` Set status of data structure as removed.
`void` `onStop()` Callback to notify local reentrant lock instance on node stop.
`void` `onUpdate(GridCacheLockState val)` Callback to notify reentrant lock on changes.
`void` `readExternal(ObjectInput in)`
`boolean` `removed()` Gets status of reentrant lock.
`String` `toString()`
`boolean` `tryLock()` Acquires the lock only if it is free at the time of invocation.
`boolean` `tryLock(long timeout, TimeUnit unit)` Acquires the lock if it is not held by another thread within the given waiting time and the current thread has not been interrupted.
`void` `unlock()` Releases the lock.
`void` `writeExternal(ObjectOutput out)`

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### GridCacheLockImpl

    public GridCacheLockImpl()

Empty constructor required by `Externalizable`.

#### GridCacheLockImpl

    public GridCacheLockImpl(String name,
                     GridCacheInternalKey key,
                     IgniteInternalCache<GridCacheInternalKey,GridCacheLockState> lockView,
                     GridCacheContext ctx)

Constructor.

Parameters:
  `name` - Reentrant lock name.
  `key` - Reentrant lock key.
  `lockView` - Reentrant lock projection.
  `ctx` - Cache context.

### Method Detail

#### onUpdate

    public void onUpdate(GridCacheLockState val)

Callback to notify reentrant lock on changes.

Specified by:
  `onUpdate` in interface `GridCacheLockEx`
Parameters:
  `val` - New reentrant lock state.

#### onNodeRemoved

    public void onNodeRemoved(UUID nodeId)

Callback to notify semaphore on topology changes.

Specified by:
  `onNodeRemoved` in interface `GridCacheLockEx`
Parameters:
  `nodeId` - Id of the node that left the grid.

#### onStop

    public void onStop()

Callback to notify local reentrant lock instance on node stop.

Specified by:
  `onStop` in interface `GridCacheLockEx`

#### name

    public String name()

Name of atomic reentrant lock.

Specified by:
  `name` in interface `IgniteLock`
Returns:
  Name of atomic reentrant lock.

#### lock

    public void lock()

Acquires the distributed reentrant lock.

Acquires the lock if it is not held by another thread and returns immediately, setting the lock hold count to one.

If the current thread already holds this lock then the hold count is incremented by one and the method returns immediately.

If the lock is held by another thread then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:

- The lock is acquired by the current thread; or
- Lock is broken (any node failed while owning this lock), and lock is created in non-failoverSafe mode.
- Local node is stopped.

Specified by:
  `lock` in interface `Lock`
Specified by:
  `lock` in interface `IgniteLock`

#### lockInterruptibly

    public void lockInterruptibly()
                           throws IgniteInterruptedException

Acquires the lock unless the current thread is interrupted.

Acquires the lock if it is not held by another thread and returns immediately, setting the lock hold count to one.

If the current thread already holds this lock then the hold count is incremented by one and the method returns immediately.

If the lock is held by another thread then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:

- The lock is acquired by the current thread; or
- Some other thread interrupts the current thread.
- Lock is broken (any node failed while owning this lock), and lock is created in non-failoverSafe mode.
- Local node is stopped.

If the lock is acquired by the current thread then the lock hold count is set to one.

If the current thread:

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

`IgniteException` is thrown in case:

- the lock is broken before or during the attempt to acquire this lock; or
- local node is stopped,

In this implementation, as this method is an explicit interruption point, preference is given to responding to the interrupt over normal or reentrant acquisition of the lock.

Specified by:
  `lockInterruptibly` in interface `Lock`
Specified by:
  `lockInterruptibly` in interface `IgniteLock`
Throws:
  `IgniteInterruptedException` - if the current thread is interrupted

#### 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 `true`. If the lock is not available then this method will return immediately with the value `false`.

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. If node is stopped, or any node failed while owning the lock in non-failoverSafe mode, then `IgniteException` is thrown.

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

#### tryLock

    public boolean tryLock(long timeout,
                  TimeUnit unit)
                    throws IgniteInterruptedException

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

Acquires the lock if it is not held by another thread and returns immediately with the value `true`, setting the lock hold count to one.

If the current thread already holds this lock then the hold count is incremented by one and the method returns `true`.

If the lock is held by another thread then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of five things happens:

- The lock is acquired by the current thread; or
- Some other thread interrupts the current thread; or
- Lock is broken (any node failed while owning this lock), and lock is created in non-failoverSafe mode.
- Local node is stopped.
- The specified waiting time elapses

If the lock is acquired then the value `true` is returned and the lock hold count is set to one.

If the current thread:

- has its interrupted status set on entry to this method; or
- is interrupted while acquiring the lock; or

then `IgniteInterruptedException` is thrown and the current thread's interrupted status is cleared.

`IgniteException` is thrown in case:

- the lock is broken before or during the attempt to acquire this lock; or
- local node is stopped,

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

In this implementation, as this method is an explicit interruption point, preference is given to responding to the interrupt over normal or reentrant acquisition of the lock, and over reporting the elapse of the waiting time.

Specified by:
  `tryLock` in interface `Lock`
Specified by:
  `tryLock` in interface `IgniteLock`
Parameters:
  `timeout` - the time to wait for the lock
  `unit` - the time unit of the timeout argument
Returns:
  `true` if the lock was free and was acquired by the current thread, or the lock was already held by the current thread; and `false` if the waiting time elapsed before the lock could be acquired
Throws:
  `IgniteInterruptedException` - if the current thread is interrupted

#### unlock

    public void unlock()

Releases the lock. If lock is not owned by current thread, then an `IllegalMonitorStateException` is thrown. If lock is already broken prior to invocation of this method, and lock is created in non-failover safe mode, then `IgniteException` is thrown.

Specified by:
  `unlock` in interface `Lock`
Specified by:
  `unlock` in interface `IgniteLock`

#### newCondition

    @NotNull
    public Condition newCondition()

Description copied from interface: `IgniteLock`
This method is not supported in IgniteLock, Any invocation of this method will result in UnsupportedOperationException. Correct way to obtain Condition object is through method IgniteLock.getOrCreateCondition(String)

Specified by:
  `newCondition` in interface `Lock`
Specified by:
  `newCondition` in interface `IgniteLock`

#### getOrCreateCondition

    public IgniteCondition getOrCreateCondition(String name)

Returns a `Condition` instance for use with this `IgniteLock` instance.

- If this lock is not held when any of the `Condition` waiting or signalling methods are called, then an `IllegalMonitorStateException` is thrown.
- When the condition waiting methods are called the lock is released and, before they return, the lock is reacquired and the lock hold count restored to what it was when the method was called.
- If a thread is interrupted while waiting then the wait will terminate, an `IgniteInterruptedException` will be thrown, and the thread's interrupted status will be cleared.
- Waiting threads are signalled in FIFO order.

Specified by:
  `getOrCreateCondition` in interface `IgniteLock`
Parameters:
  `name` - Name of the distributed condition object
Returns:
  the Condition object

#### getHoldCount

    public int getHoldCount()

Queries the number of holds on this lock by the current thread.

Specified by:
  `getHoldCount` in interface `IgniteLock`
Returns:
  the number of holds on this lock by the current thread, or zero if this lock is not held by the current thread

#### isHeldByCurrentThread

    public boolean isHeldByCurrentThread()

Queries if this lock is held by the current thread.

Specified by:
  `isHeldByCurrentThread` in interface `IgniteLock`
Returns:
  `true` if current thread holds this lock and `false` otherwise

#### isLocked

    public boolean isLocked()

Queries if this lock is held by any thread on any node. This method is designed for use in monitoring of the system state, not for synchronization control.

Specified by:
  `isLocked` in interface `IgniteLock`
Returns:
  `true` if any thread on this or any other node holds this lock and `false` otherwise

#### hasQueuedThreads

    public boolean hasQueuedThreads()

Queries whether any threads on this node are waiting to acquire this lock. Note that because cancellations may occur at any time, a `true` return does not guarantee that any other thread will ever acquire this lock. This method is designed primarily for use in monitoring of the system state.

Specified by:
  `hasQueuedThreads` in interface `IgniteLock`
Returns:
  `true` if there may be other threads on this node waiting to acquire the lock

#### hasQueuedThread

    public boolean hasQueuedThread(Thread thread)

Queries whether the given thread is waiting to acquire this lock. Note that because cancellations may occur at any time, a `true` return does not guarantee that this thread will ever acquire this lock. This method is designed primarily for use in monitoring of the system state.

Specified by:
  `hasQueuedThread` in interface `IgniteLock`
Parameters:
  `thread` - the thread
Returns:
  `true` if the given thread is queued waiting for this lock

#### hasWaiters

    public boolean hasWaiters(IgniteCondition condition)

Queries whether any threads on this node are waiting on the given condition associated with this lock. Note that because timeouts and interrupts may occur at any time, a `true` return does not guarantee that a future `signal` will awaken any threads. This method is designed primarily for use in monitoring of the system state.

Specified by:
  `hasWaiters` in interface `IgniteLock`
Parameters:
  `condition` - the condition
Returns:
  `true` if there are any waiting threads on this node

#### getWaitQueueLength

    public int getWaitQueueLength(IgniteCondition condition)

Returns an estimate of the number of threads on this node that are waiting on the given condition associated with this lock. Note that because timeouts and interrupts may occur at any time, the estimate serves only as an upper bound on the actual number of waiters. This method is designed for use in monitoring of the system state, not for synchronization control.

Specified by:
  `getWaitQueueLength` in interface `IgniteLock`
Parameters:
  `condition` - the condition
Returns:
  the estimated number of waiting threads on this node

#### isFailoverSafe

    public boolean isFailoverSafe()

Description copied from interface: `IgniteLock`
Returns `true` if this lock is safe to use after node failure. If not, IgniteInterruptedException is thrown on every other node after node failure.

Specified by:
  `isFailoverSafe` in interface `IgniteLock`
Returns:
  `true` if this reentrant lock has failoverSafe set true

#### isFair

    public boolean isFair()

Description copied from interface: `IgniteLock`
Returns `true` if this lock is fair. Fairness flag can only be set on lock creation.

Specified by:
  `isFair` in interface `IgniteLock`
Returns:
  `true` if this reentrant lock has fairness flag set true.

#### isBroken

    public boolean isBroken()

Returns true if any node that owned the locked failed before releasing the lock.

Specified by:
  `isBroken` in interface `IgniteLock`
Returns:
  true if any node failed while owning the lock since the lock on this node was initialized.

#### key

    public GridCacheInternalKey key()

Get current reentrant lock latch key.

Specified by:
  `key` in interface `GridCacheLockEx`
Returns:
  Lock key.

#### removed

    public boolean removed()

Gets status of reentrant lock.

Specified by:
  `removed` in interface `IgniteLock`
Returns:
  `true` if reentrant lock was removed from cache, `false` in other case.

#### onRemoved

    public boolean onRemoved()

Set status of data structure as removed.

Specified by:
  `onRemoved` in interface `GridCacheRemovable`
Returns:
  Current status.

#### needCheckNotRemoved

    public void needCheckNotRemoved()

Specified by:
  `needCheckNotRemoved` in interface `GridCacheRemovable`

#### writeExternal

    public void writeExternal(ObjectOutput out)
                       throws IOException

Specified by:
  `writeExternal` in interface `Externalizable`
Throws:
  `IOException`

#### readExternal

    public void readExternal(ObjectInput in)
                      throws IOException,
                             ClassNotFoundException

Specified by:
  `readExternal` in interface `Externalizable`
Throws:
  `IOException`
  `ClassNotFoundException`

#### close

    public void close()

Removes reentrant lock.

Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `IgniteLock`

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.8.0
Release Date | : December 5 2016