com.thinkaurelius.titan.diskstorage.locking

Class AbstractLocker<S extends LockStatus>

java.lang.Object

com.thinkaurelius.titan.diskstorage.locking.AbstractLocker<S>

Type Parameters:

S - An implementation-specific type holding information about a single lock; see ConsistentKeyLockStatus for an example

All Implemented Interfaces:

Locker

Direct Known Subclasses:

ConsistentKeyLocker

public abstract class AbstractLocker<S extends LockStatus>
extends Object
implements Locker

Abstract base class for building lockers. Implements locking between threads using LocalLockMediator but delegates inter-process lock resolution to its subclasses.

See Also:

ConsistentKeyLocker

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AbstractLocker.Builder<S,B extends AbstractLocker.Builder<S,B>> Abstract builder for this Locker implementation.

Field Summary

Fields

Modifier and Type	Field and Description
protected LocalLockMediator<StoreTransaction>	llm Resolves lock contention by multiple threads.
protected Duration	lockExpire The amount of time, in times.getUnit(), that may pass after writing a lock before it is considered to be invalid and automatically unlocked.
protected LockerState<S>	lockState Stores all information about all locks this implementation has taken on behalf of any StoreTransaction.
protected org.slf4j.Logger	log
protected StaticBuffer	rid Uniquely identifies a process within a domain (or across all domains, though only intra-domain uniqueness is required)
protected ConsistentKeyLockerSerializer	serializer This is sort-of Cassandra/HBase specific.
protected TimestampProvider	times Sole source of time.
protected TimeUnit	timeUnit This is a copy of times.getUnit().

Constructor Summary

Constructors

Constructor and Description
AbstractLocker(StaticBuffer rid, TimestampProvider times, ConsistentKeyLockerSerializer serializer, LocalLockMediator<StoreTransaction> llm, LockerState<S> lockState, Duration lockExpire, org.slf4j.Logger log)

Method Summary

Methods

Modifier and Type	Method and Description
void	checkLocks(StoreTransaction tx) Verify that all previous Locker.writeLock(KeyColumn, StoreTransaction) calls with tx actually succeeded.
protected abstract void	checkSingleLock(KeyColumn lockID, S lockStatus, StoreTransaction tx) Try to verify that the lock identified by lockID is already held by tx.
void	deleteLocks(StoreTransaction tx) Release every lock currently held by tx.
protected abstract void	deleteSingleLock(KeyColumn lockID, S lockStatus, StoreTransaction tx) Try to unlock/release/delete the lock identified by lockID and both held by and verified for tx.
void	writeLock(KeyColumn lockID, StoreTransaction tx) Attempt to acquire/take/claim/write the lock named by lockID.
protected abstract S	writeSingleLock(KeyColumn lockID, StoreTransaction tx) Try to take/acquire/write/claim a lock uniquely identified within this Locker by the lockID argument on behalf of tx.

Methods inherited from class java.lang.Object

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

Field Detail

rid

protected final StaticBuffer rid

Uniquely identifies a process within a domain (or across all domains, though only intra-domain uniqueness is required)

times

protected final TimestampProvider times

Sole source of time. All fields of type long that represent times or durations should be expressed in terms of TimestampProvider.getUnit(). Furthermore, if the locking backend allows the client to set a timestamp on writes, those timestamps should be in the same units.

Don't call System.currentTimeMillis() or System.nanoTime() directly. Use only this object. This object is replaced with a mock during testing to give tests exact control over the flow of time.

timeUnit

protected final TimeUnit timeUnit

This is a copy of times.getUnit(). This field shouldn't exist. The JIT will undoubtedly inline getUnit() so this just wastes space and duplicates information. It's only here to ease testing with EasyMock. By calling getUnit() only during construction and never during normal operation, it's easier to create a strict method-order-checking mock of TimestampProvider in testing.

serializer

protected final ConsistentKeyLockerSerializer serializer

This is sort-of Cassandra/HBase specific. It concatenates KeyColumn arguments into a single StaticBuffer containing the key followed by the column and vice-versa.

llm

protected final LocalLockMediator<StoreTransaction> llm

Resolves lock contention by multiple threads.

lockState

protected final LockerState<S extends LockStatus> lockState

Stores all information about all locks this implementation has taken on behalf of any StoreTransaction. It is parameterized in a type specific to the concrete subclass, so that concrete implementations can store information specific to their locking primitives.

lockExpire

protected final Duration lockExpire

The amount of time, in times.getUnit(), that may pass after writing a lock before it is considered to be invalid and automatically unlocked.

log

protected final org.slf4j.Logger log

Constructor Detail

AbstractLocker

public AbstractLocker(StaticBuffer rid,
              TimestampProvider times,
              ConsistentKeyLockerSerializer serializer,
              LocalLockMediator<StoreTransaction> llm,
              LockerState<S> lockState,
              Duration lockExpire,
              org.slf4j.Logger log)

Method Detail

writeSingleLock

protected abstract S writeSingleLock(KeyColumn lockID,
                StoreTransaction tx)
                                                 throws Throwable

Try to take/acquire/write/claim a lock uniquely identified within this Locker by the lockID argument on behalf of tx.

Parameters:

lockID - identifies the lock

tx - identifies the process claiming this lock

Returns:

a LockStatus implementation on successful lock aquisition

Throws:

Throwable - if the lock could not be taken/acquired/written/claimed or the attempted write encountered an error

checkSingleLock

protected abstract void checkSingleLock(KeyColumn lockID,
                   S lockStatus,
                   StoreTransaction tx)
                                 throws Throwable

Try to verify that the lock identified by lockID is already held by tx. The lockStatus argument refers to the object returned by a previous call to writeSingleLock(KeyColumn, StoreTransaction). This should be a read-only operation: return if the lock is already held, but this method finds that it is not held, then throw an exception instead of trying to acquire it.

This method is only useful with nonblocking locking implementations try to lock and then check the outcome of the attempt in two separate stages. For implementations that build writeSingleLock(...) on a synchronous locking primitive, such as a blocking lock() method or a blocking semaphore p(), this method is redundant with writeSingleLock(...) and may unconditionally return true.

Parameters:

lockID - identifies the lock to check

lockStatus - the result of a prior successful writeSingleLock(...) call on this lockID and tx

tx - identifies the process claiming this lock

Throws:

Throwable - if the lock fails the check or if the attempted check encountered an error

deleteSingleLock

protected abstract void deleteSingleLock(KeyColumn lockID,
                    S lockStatus,
                    StoreTransaction tx)
                                  throws Throwable

Try to unlock/release/delete the lock identified by lockID and both held by and verified for tx. This method is only called with arguments for which writeSingleLock(KeyColumn, StoreTransaction) and checkSingleLock(KeyColumn, LockStatus, StoreTransaction) both returned successfully (i.e. without exceptions).

Parameters:

lockID - identifies the lock to release

lockStatus - the result of a prior successful writeSingleLock(...) followed by a successful checkSingleLock(...)

tx - identifies the process that wrote and checked this lock

Throws:

Throwable - if the lock could not be released/deleted or if the attempted delete encountered an error

writeLock

public void writeLock(KeyColumn lockID,
             StoreTransaction tx)
               throws TemporaryLockingException,
                      PermanentLockingException

Description copied from interface: Locker

Attempt to acquire/take/claim/write the lock named by lockID.

Returns on success and throws an exception on failure.

Specified by:

writeLock in interface Locker

Parameters:

lockID - the lock to acquire

tx - the transaction attempting to acquire the lock

Throws:

TemporaryLockingException - a failure likely to disappear if the call is retried

PermanentLockingException - a failure unlikely to disappear if the call is retried

checkLocks

public void checkLocks(StoreTransaction tx)
                throws TemporaryLockingException,
                       PermanentLockingException

Description copied from interface: Locker

Verify that all previous Locker.writeLock(KeyColumn, StoreTransaction) calls with tx actually succeeded.

Returns on success and throws an exception on failure.

Specified by:

checkLocks in interface Locker

Parameters:

tx - the transaction attempting to check the result of previous writeLock(..., tx) calls in which it was the tx argument

Throws:

TemporaryLockingException - a failure likely to disappear if the call is retried

PermanentLockingException - a failure unlikely to disappear if the call is retried

deleteLocks

public void deleteLocks(StoreTransaction tx)
                 throws TemporaryLockingException,
                        PermanentLockingException

Description copied from interface: Locker

Release every lock currently held by tx.

Returns on success and throws an exception on failure.

Specified by:

deleteLocks in interface Locker

Parameters:

tx - the transaction attempting to delete locks taken in previous writeLock(..., tx) calls in which it was the tx argument

Throws:

TemporaryLockingException - a failure likely to disappear if the call is retried

PermanentLockingException - a failure unlikely to disappear if the call is retried