com.thinkaurelius.titan.diskstorage.locking

Interface Locker

All Known Implementing Classes:

AbstractLocker, ConsistentKeyLocker

public interface Locker

Threadsafe discretionary locking within and between processes Titan.

Locks are identified KeyColumn instances. KeyColumn#equals(Object) should be used to determine whether two KeyColumn instances refer to the same or different locks.

Threads taking locks are identified by StoreTransaction instances. Either equals(...) or reference equality (the == operator) can be used to compare these instances.

This interface follows a three-step locking model that supports both nonblocking and blocking locking primitives. Not all Titan StoreTransactions will need locks and use this interface. For those StoreTransactions that do take one or more locks, Titan will call the methods on this interface in the following order. tx refers to the same StoreTransaction instance in each step.

1. writeLock(kc, tx) one or more times per distinct KeyColumn kc
2. checkLocks(tx) once if the user commits tx or never if the user aborts tx
3. deleteLocks(tx) once, regardless of whether checkLocks(tx) was called

The first step, writeLocks, attempts to take a lock. This may, but need not necessarily, indicate whether the attempt succeeded or failed. The second step, checkLocks, returns if all previous writeLocks succeeded or throws an exception if one or more failed. The final step, deleteLocks, releases all locks and associated resources held by the tx.

All implementations of this interface must be safe for concurrent use by different threads. However, implementations may assume that, for any given StoreTransaction tx, all calls to this interface's methods with argument tx will either come from a single thread or multiple threads using external synchronization to provide the same effect.

Method Summary

Methods

Modifier and Type	Method and Description
void	checkLocks(StoreTransaction tx) Verify that all previous writeLock(KeyColumn, StoreTransaction) calls with tx actually succeeded.
void	deleteLocks(StoreTransaction tx) Release every lock currently held by tx.
void	writeLock(KeyColumn lockID, StoreTransaction tx) Attempt to acquire/take/claim/write the lock named by lockID.

Method Detail

writeLock

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

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

Returns on success and throws an exception on failure.

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

void checkLocks(StoreTransaction tx)
                throws TemporaryLockingException,
                       PermanentLockingException

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

Returns on success and throws an exception on failure.

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

void deleteLocks(StoreTransaction tx)
                 throws TemporaryLockingException,
                        PermanentLockingException

Release every lock currently held by tx.

Returns on success and throws an exception on failure.

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