net.openhft.chronicle.hash.locks

Interface InterProcessLock

All Superinterfaces:

Lock

public interface InterProcessLock
extends Lock

An inter-process lock, used to control access to some shared off-heap resources of ChronicleHash instances.

This lock is not reentrant, but kind of "saturating": multiple lock() calls have the same effect as a single call. Likewise unlock() -- multiple unlocks, or unlocking when the lock isn't actually held, has no negative effects.

Once a lock object obtained, it shouldn't be stored in a field and accessed from multiple threads, instead of that, lock objects should be obtained in each thread separately, using the same call chain. This is because since the lock is inter-process, it anyway keeps it's synchronization state in shared off-heap memory, but restricting on-heap "view" of shared lock to a single thread is beneficial form performance point-of-view, e. g. fields of the on-heap InterProcessLock object shouldn't be volatile.

Lock is inter-process, hence it cannot afford to wait for acquisition infinitely, because it would be too dead-lock prone. lock() throws RuntimeException after some implementation-defined time spent in waiting for the lock acquisition.

InterProcessLock supports interruption of lock acquisition (in lockInterruptibly() and Lock.tryLock(long, TimeUnit) methods).

See Also:

InterProcessReadWriteUpdateLock

Implementation Note:

Inter-process lock is unfair.

Method Summary

Modifier and Type	Method and Description
boolean	isHeldByCurrentThread() Checks if this lock is held by current thread.
void	lock() Acquires the lock.
void	lockInterruptibly() Acquires the lock unless the current thread is interrupted.
default @NotNull Condition	newCondition() Conditions are not supported by inter-process locks, always throws UnsupportedOperationException.
boolean	tryLock() Acquires the lock only if it is free at the time of invocation, also if the lock is already held by the current thread, this call immediately returns true.
void	unlock() Releases the lock (and all stronger-level lock, in the context of InterProcessReadWriteUpdateLock, if the lock is not held by the current thread, returns immediately.

Methods inherited from interface java.util.concurrent.locks.Lock

tryLock

Method Detail

isHeldByCurrentThread

boolean isHeldByCurrentThread()

Checks if this lock is held by current thread.

lock

void lock()

Acquires the lock. If this lock (or a stronger-level lock, in the context of InterProcessReadWriteUpdateLock) is already held by the current thread, this call returns immediately.

If the lock is not available then the current thread enters a busy loop. After some threshold time spent in a busy loop, the thread might be disabled for thread scheduling purposes and lay dormant until the lock has been acquired. After some implementation-defined time spent in waiting for the lock acquisition, InterProcessDeadLockException is thrown.

Specified by:

lock in interface Lock

Throws:

IllegalMonitorStateException - if this method call observes illegal lock state, or some lock limitations reached (e. g. maximum read lock holders)

InterProcessDeadLockException - if fails to acquire a lock for some finite time

lockInterruptibly

void lockInterruptibly()
                throws InterruptedException

Acquires the lock unless the current thread is interrupted. If the current thread is not interrupted, and this lock (or a stronger-level lock, in the context of InterProcessReadWriteUpdateLock) is already held by the current thread, this call returns immediately.

If the lock is not available then the current thread enters a busy loop, and after some threshold time spend in a busy loop, the thread might be disabled for thread scheduling purposes and lay dormant until one of three things happens:

• The lock is acquired by the current thread, then lockInterruptibly() successfully returns.
• Some other thread interrupts the current thread, then InterruptedException is thrown and the current thread's interrupted status is cleared.
• Some implementation-defined time is spent in waiting for the lock acquisition, then InterProcessDeadLockException is thrown.

Specified by:

lockInterruptibly in interface Lock

Throws:

InterruptedException - if the current thread is interrupted while acquiring the lock

IllegalMonitorStateException - if this method call observes illegal lock state, or some lock limitations reached (e. g. maximum read lock holders)

InterProcessDeadLockException - if fails to acquire a lock for some finite time

tryLock

boolean tryLock()

Acquires the lock only if it is free at the time of invocation, also if the lock is already held by the current thread, this call immediately returns true.

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.

Specified by:

tryLock in interface Lock

Returns:

true if the lock was acquired and false otherwise

Throws:

IllegalMonitorStateException - if this method call observes illegal lock state, or some lock limitations reached (e. g. maximum read lock holders)

API Note:

Example usage:

 try (ExternalMapQueryContext<K, V, ?> q = map.queryContext(key)) {
     if (q.updateLock().tryLock()) {
         // highly-probable branch
         if (q.entry() != null) {
             // upgrade to write lock
             q.writeLock().lock();
             q.remove(q.entry());
         } else {
             // ...
         }
     } else {
         // if failed to acquire the update lock without waiting, go acquire the write lock
         // right away, because probability that we will need to upgrade to write lock anyway
         // is high.
         q.writeLock().lock();
         if (q.entry() != null) {
             q.remove(q.entry());
         } else {
             // ...
         }
     }
 }

unlock

void unlock()

Releases the lock (and all stronger-level lock, in the context of InterProcessReadWriteUpdateLock, if the lock is not held by the current thread, returns immediately.

Specified by:

unlock in interface Lock

Throws:

IllegalMonitorStateException - if this method call observes illegal lock state

newCondition

@NotNull
default @NotNull Condition newCondition()

Conditions are not supported by inter-process locks, always throws UnsupportedOperationException.

Specified by:

newCondition in interface Lock

Returns:

nothing, always throws an exception

Throws:

UnsupportedOperationException - always