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 `StoreTransaction`s will need locks and use this interface. For those `StoreTransaction`s 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

Copyright © 2012–2014. All rights reserved.