class ChainLockTransaction

UntilDone provides a common sequence for executing a chain lock transaction and the required

backoff arbitration logic.

The caller is responsble for providing three arguments:

1. An instance of Option

<constant

>: Used to pass a compile-time constant to the environment-

provided StateSaver

<constant

> type, indicating the relevant states to save, such as IRQ

enable flags, preemption flags, etc..., and restore after each transaction attempt.

2. An instance of CallsiteTraits

<Derived

>::CallsiteInfo: Used for debugging and tracing to

identify the code location of the transaction.

3. A callable implementing a single transaction attempt: This can be a function, lambda, or

functor with an appropriate signature and static annotations.

The callable should be invocable matching one of the following signatures:

a. ChainLockTransactionCommon::Result

<

>() : A transaction that has a return type void.

c. ChainLockTransactionCommon::Result

<T

>(): A transaction that has user defined return type T.

b. ChainLockTransactionCommon::DoneType() : A transaction that has an implied return type void.

The overall return type of UntilDone is either T or void, depending on signature of Callable,

as described above. Note that Result

<

>, Result

<T

>, and DoneType are transitively inherited

from ChainLockTransactionCommon through this ChainLockTransaction CRTP type and may be referred

to using the environment-specific transaction type.

A basic transaction is structured as follows:

1. Define a callable that will be executed until the transaction is complete. In this example,

the callable will return zx_status_t when the transaction is complete, which will become the

return value of UntilDone.

auto do_transaction = [

&

]() __TA_REQUIRES(chainlock_transaction_token,

<env

-specific tokens>)

-> ChainLockTransaction::Result

<zx

_status_t> {

if (!object->get_lock().AcquireOrBackoff()) {

return ChainLockTransaction::Action::Backoff; // Execute the backoff protocol and re-enter.

}

if (restart_transaciton_condition) {

object->get_lock().Release();

return ChainLockTransaction::Action::Restart; // Restart the transaction and re-enter.

}

if (!LockedOperationOnObject(object)) {

object->get_lock().Release();

return ZX_ERR_BAD_STATE; // Complete the transaction, returning the error to the caller.

}

object->get_lock().Release();

return ZX_OK; // Complete the transaction, returning success to the caller.

};

In cases where the return user return type is void, the callable can return

ChainLockTransaction::Done to complete the transaction.

2. Execute the transaction using the given options and callable. In this example, the constant

kStateOptionA is a value of type Option

<auto

option> with an environment-specific option value

to pass to the state saver. The callable is invoked cyclically, with intervening backoffs,

until a terminal value (of a user defined return type in this case) is returned.

return ChainLockTransaction::UntilDone(kStateOptionA, CLT_CALLSITE("foo"), do_transaction);

Debug asserts for various transaction states.

Assert that a transaction is active to static analysis.

Assert that a transaction is active to static analysis without actually checking at runtime for

efficiency in trivial cases.

Returns a reference to the active transaction. Asserts that a transaction is active.

Saves the pointer to the current transaction and allocates a reserved token to sync leaf chain

locks to during critical sequences.

Create a save state for a bare transaction used to kick off a new thread.

Restore the active transaction using the given saved state.

Directly finalize the transaction, ending an active contention tracing duration, if any.

Restarts this transaction, resetting key state including the callsite info.

Escape hatch methods allowing transactions to be instantiated outside the scope of the

preferred UntilDone interface.