net.openhft.chronicle.hash.locks

Interface InterProcessReadWriteUpdateLock

All Superinterfaces:

ReadWriteLock

All Known Subinterfaces:

ExternalHashQueryContext<K>, ExternalMapQueryContext<K,V,R>, ExternalSetQueryContext<K,R>, HashQueryContext<K>, MapQueryContext<K,V,R>, MapRemoteQueryContext<K,V,R>, SegmentLock, SetQueryContext<K,R>, SetRemoteQueryContext<K,R>

All Known Implementing Classes:

CompiledMapIterationContext, CompiledMapQueryContext, CompiledReplicatedMapIterationContext, CompiledReplicatedMapQueryContext

public interface InterProcessReadWriteUpdateLock
extends ReadWriteLock

Tri-level lock, for efficient handling of concurrent accesses, that requre different privileges. For grasping multi-level lock concept and basic semantic principles, please read ReadWriteLock documentation.

Read lock is for "readers". Multiple threads might hold read lock simultaneously. Read lock held by any thread prevents write lock from being acquired.

Update lock is for writers, who must access the resource exclusively with each other, but write safely for concurrent readers. Only one thread could hold update or write lock at the same time, but update lock doesn't prevent concurrent readers to come.

Write lock is for writers, which need total exclusiveness. When write lock is held, nobody may access the resource at the same time.

Same as InterProcessLock itself, the InterProcessReadWriteUpdateLock as a whole is saturating: when stronger-level lock is acquired, all weaker-level locks are thought to be acquired as well ("saturated"). Unlocking a weaker-level lock "desaturates" it with stronger-level locks only. This means that try-finally pattern looks unusual:

 l.writeLock().lock(); // acquires all three level locks
 try {
     // do something
 } finally {
     l.readLock().unlock();
     // l.writeLock().unlock(); - INCORRECT, because "desaturates" only write-level,
     // leaving read lock and update lock held
 }

However, if you use InterProcessReadWriteUpdateLock as a part of ExternalHashQueryContext query, you shouldn't keep this peculiarity in mind, because ExternalHashQueryContext.close() handles unlocking for you.

Any downgrades ("desaturations") are possible, but only update -> write upgrade is allowed. This is so to prevent dead locks: for example, imagine, that two threads came and acquired read locks, and then both try to upgrade to write lock, blocking each other indefinitely.

This interface is based on this work, might be useful to read to understand read-write-update lock idea, and how to use this concept.

Same as InterProcessLock, instances of this interface are for single-thread use only. Views of the same inter-process lock should be obtained in different threads independently. See InterProcessLock documentation for rationalization of this.

See Also:

InterProcessLock, ReadWriteLock

Method Summary

Modifier and Type	Method and Description
InterProcessLock	readLock() Returns the read-level lock.
InterProcessLock	updateLock() Returns the update-level lock.
InterProcessLock	writeLock() Returns the write-level lock.

Method Detail

readLock

@NotNull
InterProcessLock readLock()

Returns the read-level lock. Calling unlock() on this lock also releases the update and write locks, if held, as well.

Specified by:

readLock in interface ReadWriteLock

Returns:

the read level lock

updateLock

@NotNull
InterProcessLock updateLock()

Returns the update-level lock. Calling lock() or other locking methods (tryLock(), etc.) on this lock acquires the read lock, as well. Calling unlock() on this lock also releases the write lock.

Any attempt to acquire this lock (including tryLock(), if the read lock is already held by the current thread, but the update lock is not yet, is prevented by throwing IllegalInterProcessLockStateException.

Returns:

the update-level lock

writeLock

@NotNull
InterProcessLock writeLock()

Returns the write-level lock. Calling lock() or other locking methods (tryLock(), etc.) on this lock acquires the read and update locks, as well.

Any attempt to acquire this lock (including tryLock(), if the read lock is already held by the current thread, but the update and write locks are not yet, is prevented by throwing IllegalInterProcessLockStateException.

Specified by:

writeLock in interface ReadWriteLock

Returns:

the update-level lock