Trait TransactionHooks 

pub unsafe trait TransactionHooks: Sized + 'static {
    type ContentionState: ContentionState;
    type CallsiteInfo: Copy;
    type Accounting: AccountingStorage;
    type Tracing: TraceStorage<Self::CallsiteInfo>;
    type ExtraState: Default;

    // Required methods
    fn active() -> Option<NonNull<ChainLockTransaction<Self>>>;
    unsafe fn set_active(
        transaction: Option<NonNull<ChainLockTransaction<Self>>>,
    );
    fn yield_cpu();
    fn allocate_reserved_token() -> Token;
    fn record_backoff_or_retry(
        transaction: &ChainLockTransaction<Self>,
        observed_token: Token,
        lock_state: &AtomicToken,
        contention_state: &Self::ContentionState,
    ) -> bool;
    fn release_and_notify<F: FnOnce()>(
        transaction: &ChainLockTransaction<Self>,
        contention_state: &Self::ContentionState,
        do_release: F,
    );

    // Provided methods
    fn get_current_ticks() -> i64 { ... }
    fn on_finalized(
        _contention_start_ticks: i64,
        _callsite_info: Self::CallsiteInfo,
    ) { ... }
    fn on_backoff(_transaction: &ChainLockTransaction<Self>) { ... }
}

Environment-specific hooks required by ChainLockTransaction.

Safety

Implementors must ensure that:

• Self::active returns the exact pointer most recently passed to Self::set_active on the current execution context (or None if Self::set_active has not been called or was most recently called with None on the current execution context).
• The storage backing Self::active and Self::set_active is strictly local to the current execution context (e.g., per-CPU or thread-local storage) and is never shared across concurrently executing contexts.

Required Associated Types

type ContentionState: ContentionState

State used by ChainLock to store contended lock state for backoff mitigation (e.g., AtomicU32 for cpu_mask_t in the Zircon kernel).

type CallsiteInfo: Copy

Debugging/tracing information that identifies the code location of the transaction.

type Accounting: AccountingStorage

Storage for debug lock accounting (SelectAccounting<ENABLED>).

type Tracing: TraceStorage<Self::CallsiteInfo>

Storage for contention spin tracing (SelectTracing<ENABLED, Self::CallsiteInfo>).

type ExtraState: Default

Additional environment-specific state stored in each transaction instance (e.g., Cell<u64> for conflict_id_ in the Zircon kernel, or () when none is needed).

Required Methods

fn active() -> Option<NonNull<ChainLockTransaction<Self>>>

Returns a pointer to the active chain lock transaction for the current execution context (e.g., current CPU), or None if none is active.

unsafe fn set_active(transaction: Option<NonNull<ChainLockTransaction<Self>>>)

Sets the active chain lock transaction for the current execution context.

Safety

The caller must ensure that transaction is either None or points to a valid ChainLockTransaction<Self> that remains alive and pinned at its memory address for as long as it remains registered as the active transaction on the current execution context.

fn yield_cpu()

Performs an architecture-specific CPU relax/yield operation.

fn allocate_reserved_token() -> Token

Allocates a reserved token for use with ChainLockTransaction::save_state_and_use_reserved_token and ChainLockTransaction::save_state_initial.

fn record_backoff_or_retry( transaction: &ChainLockTransaction<Self>, observed_token: Token, lock_state: &AtomicToken, contention_state: &Self::ContentionState, ) -> bool

Handles backoff mitigation when contention with a higher-priority transaction is observed.

Returns true if the backoff was recorded and the caller should unwind held locks, or false if the lock’s token changed and the caller should retry acquisition.

fn release_and_notify<F: FnOnce()>( transaction: &ChainLockTransaction<Self>, contention_state: &Self::ContentionState, do_release: F, )

Carefully sequences the operations required to release a ChainLock and notify backed-off contenders.

Provided Methods

fn get_current_ticks() -> i64

Gets the current monotonic ticks for contention spin tracing.

fn on_finalized( _contention_start_ticks: i64, _callsite_info: Self::CallsiteInfo, )

Emits a trace event or updates counters when a contended transaction is finalized.

fn on_backoff(_transaction: &ChainLockTransaction<Self>)

Updates counters or state when a transaction backs off (invoked after incrementing backoff_count).

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors