Struct LockManager

pub struct LockManager { /* private fields */ }

LockManager holds the locks that transactions might have taken. A TransactionManager implementation would typically have one of these.

Three different kinds of locks are supported. There are read locks and write locks, which are as one would expect. The third kind of lock is a transaction lock (which is also known as an upgradeable read lock). When first acquired, these block other writes (including other transaction locks) but do not block reads. When it is time to commit a transaction, these locks are upgraded to full write locks (without ever dropping the lock) and then dropped after committing (unless commit_and_continue is used). This way, reads are only blocked for the shortest possible time. It follows that write locks should be used sparingly. Locks are granted in order with one exception: when a lock is in the initial transaction lock state (LockState::Locked), all read locks are allowed even if there are other tasks waiting for the lock. The reason for this is because we allow read locks to be taken by tasks that have taken a transaction lock (i.e. recursion is allowed). In other cases, such as when a writer is waiting and there are only readers, readers will queue up behind the writer.

To summarize:

+———————––+—————–+––––––––+——————+ | | While read_lock | While txn_lock | While write_lock | | | is held | is held | is held | +———————––+—————–+––––––––+——————+ | Can acquire read_lock? | true | true | false | +———————––+—————–+––––––––+——————+ | Can acquire txn_lock? | true | false | false | +———————––+—————–+––––––––+——————+ | Can acquire write_lock? | false | false | false | +———————––+—————–+––––––––+——————+

Implementations

impl LockManager

pub fn new() -> Self

pub async fn txn_lock<'a>(&'a self, lock_keys: LockKeys) -> TransactionLocks<'a>

Acquires the locks. It is the caller’s responsibility to ensure that drop_transaction is called when a transaction is dropped i.e. the filesystem’s drop_transaction method should call LockManager’s drop_transaction method.

pub fn drop_transaction(&self, transaction: &mut Transaction<'_>)

This should be called by the filesystem’s drop_transaction implementation.

pub async fn commit_prepare(&self, transaction: &Transaction<'_>)

Prepares to commit by waiting for readers to finish.

pub async fn read_lock<'a>(&'a self, lock_keys: LockKeys) -> ReadGuard<'a>

Acquires a read lock for the given keys. Read locks are only blocked whilst a transaction is being committed for the same locks. They are only necessary where consistency is required between different mutations within a transaction. For example, a write might change the size and extents for an object, in which case a read lock is required so that observed size and extents are seen together or not at all.

pub async fn write_lock<'a>(&'a self, lock_keys: LockKeys) -> WriteGuard<'a>

Acquires a write lock for the given keys. Write locks provide exclusive access to the requested lock keys.

pub fn downgrade_locks(&self, lock_keys: &LockKeys)

Downgrades locks from the WriteLock state to Locked state. This will panic if the locks are not in the WriteLock state.