class ChainLockGuard

Unconditionally acquires the given chain lock.

Releases the capability guarded by this instance without actually releasing the lock. This is

intended to be used with the Take constructor, which acquires the capability, to move

responsibility for the lock to another guard.

Conditionally acquires the lock or returns false because of backoff.

Conditionally acquires the lock or returns false if failed.

Conditionally acquires the lock, using the given callable, or returns false if failed. This is

useful in certain locking patterns where an additional predicate needs to be injected into the

lock condition.

Releases the guarded lock and its capability.

Prevents this guard from releasing the lock when it goes out of scope, but does not release the

lock or its capability. This is a temporary workaround to allow guards to be used in scopes

that will release the guarded lock in a function or method called in the guarded scope.

Example:

{

ChainLockGuard guard{object->get_lock()};

// Validation with lock held ...

guard.Unguard(); // Avoid double release when guard destructs.

DoOperationAndReleaseLock(object);

}

Possible alternatives to explore that could replace this workaround:

1. Move the guard into the callee that will release the lock:

DoOperationAndReleaseLock(object, guard.take());

2. Make the guard destructor check that that lock is actually held to avoid the double release:

~ChainLockGuard() __TA_RELEASE() {

if (held_

&

&

lock_.is_held()) {

lock_.Release();

}

}

All of these approaches have potential advantages and disadvantages that need to be considered.

Releases the lock if currently held.

Adopts the given chain lock that is already acquired via some other mechanism.

Associates the given lock capability with this scoped capability, but does not acquire it. This

is useful in conjunction with the conditional acquire methods below.

Example:

ChainLockGuard guard{lock, ChainLockGuard::Defer};

if (guard.AcquireOrBackoff()) {

// Lock is acquired and guarded. It will be released when guard goes out of scope.

} else {

// Lock is not acquired or guarded. It will not be released when guard goes out of scope.

}

NOTE: This method is correctly annotated for static analysis to understand when this scoped

capability does and does not hold the lock. The excludes annotation on the constructor tells

static analysis which capability to associate with the scoped capability instance in the "not

held" state. Later, methods annotated with acquire or release can change the state to "held"

and back to "not held", respectively.

Takes responsibility for the given lock from the given guard. This is useful for moving the

scope of a lock acquisition deeper into the call stack in certain locking patterns.

Asserts that the given guard actually holds the given lock.