Trait RunnerHooks

pub trait RunnerHooks {
    // Provided methods
    fn on_attempt_start(&self, _trx: &Transaction, _attempt: usize) { ... }
    fn before_commit(
        &self,
        _trx: &Transaction,
        _attempt: usize,
    ) -> impl Future<Output = FdbResult<()>> + Send { ... }
    fn on_hook_error(&self, _err: &FdbError, _attempt: usize) { ... }
    fn on_commit_success(
        &self,
        _committed: &TransactionCommitted,
        _commit_duration_ms: u64,
        _attempt: usize,
    ) { ... }
    fn on_commit_error(
        &self,
        _err: &TransactionCommitError,
        _attempt: usize,
    ) -> impl Future<Output = FdbResult<()>> + Send { ... }
    fn on_closure_error(&self, _err: &FdbError, _attempt: usize) { ... }
    fn on_error_duration(&self, _duration_ms: u64, _attempt: usize) { ... }
    fn on_retry(&self, _attempt: usize) { ... }
    fn on_complete(&self) { ... }
}

Observation points of the retry runner.

Hooks are purely observational: nothing they do or return changes what the runner decides. Use a RetryPolicy to influence retries. Every method has a no-op default, so an implementation only overrides what it needs.

Ordering

Every callback receives the index of the attempt it belongs to, starting at 0 and matching AttemptMetrics::index. Per attempt, in order:

1. on_attempt_start
2. the closure runs
3. if the closure succeeded: before_commit, then the commit
   • commit succeeded: on_commit_success, the run is over
   • commit failed: on_commit_error, then on_error, then on_error_duration and on_retry if the transaction was retried
4. if the closure failed: on_closure_error (only when the error maps to an FdbError, that is when the runner is about to call on_error), then on_error, then on_error_duration and on_retry if the transaction was retried

on_complete fires exactly once per run, on every exit path: success, non-retryable error, exhausted retries or binding error.

The two fallible hooks (before_commit and on_commit_error) never abort the runner: their error is reported to on_hook_error and the run continues exactly as if they had succeeded.

Transaction access

Hooks see a &Transaction, never the clonable RetryableTransaction: a hook that could keep a reference to it would make the runner fail with FdbBindingError::ReferenceToTransactionKept.

Composition

RunnerHooks is implemented for () (no-op), &H, Option<H> (None is a no-op) and (A, B), which nest for any arity: (a, (b, c)). In a tuple, callbacks fire left to right, and both sides always run even if the left one returned an error, the first error being the one reported.

Provided Methods

fn on_attempt_start(&self, _trx: &Transaction, _attempt: usize)

Called when an attempt starts, before the closure runs.

fn before_commit( &self, _trx: &Transaction, _attempt: usize, ) -> impl Future<Output = FdbResult<()>> + Send

Called after the closure succeeded, before the transaction is committed.

This is the last point where the transaction can be read or written inside the attempt. Returning an error does not abort the commit: it is reported through on_hook_error and the transaction is committed anyway.

fn on_hook_error(&self, _err: &FdbError, _attempt: usize)

Called with the error of a hook that failed, right after it failed.

fn on_commit_success( &self, _committed: &TransactionCommitted, _commit_duration_ms: u64, _attempt: usize, )

Called after a successful commit, with the time the commit took.

fn on_commit_error( &self, _err: &TransactionCommitError, _attempt: usize, ) -> impl Future<Output = FdbResult<()>> + Send

Called when the commit failed, before on_error resets the transaction. This is the only window to read conflicting keys or inspect the state of the failed attempt.

It fires whatever the runner does next, including when the RetryPolicy turns the failure into a fatal one. An error returned here is reported through on_hook_error and changes nothing else.

fn on_closure_error(&self, _err: &FdbError, _attempt: usize)

Called when a closure error is about to be handed to on_error.

A closure error classified as RetryDecision::Retry surfaces here as a synthetic FdbError with code 1020 (not_committed). A fatal error never reaches this hook.

fn on_error_duration(&self, _duration_ms: u64, _attempt: usize)

Called after on_error returned, with the time it took, backoff included.

fn on_retry(&self, _attempt: usize)

Called when the attempt is about to be retried, that is once on_error accepted to retry it.

fn on_complete(&self)

Called exactly once when the run ends, whatever its outcome.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl RunnerHooks for ()

impl<A: RunnerHooks + Sync, B: RunnerHooks + Sync> RunnerHooks for (A, B)

fn on_attempt_start(&self, trx: &Transaction, attempt: usize)

async fn before_commit( &self, trx: &Transaction, attempt: usize, ) -> FdbResult<()>

fn on_hook_error(&self, err: &FdbError, attempt: usize)

fn on_commit_success( &self, committed: &TransactionCommitted, commit_duration_ms: u64, attempt: usize, )

async fn on_commit_error( &self, err: &TransactionCommitError, attempt: usize, ) -> FdbResult<()>

fn on_closure_error(&self, err: &FdbError, attempt: usize)

fn on_error_duration(&self, duration_ms: u64, attempt: usize)

fn on_retry(&self, attempt: usize)

fn on_complete(&self)

impl<H: RunnerHooks + Sync> RunnerHooks for Option<H>

fn on_attempt_start(&self, trx: &Transaction, attempt: usize)

async fn before_commit( &self, trx: &Transaction, attempt: usize, ) -> FdbResult<()>

fn on_hook_error(&self, err: &FdbError, attempt: usize)

fn on_commit_success( &self, committed: &TransactionCommitted, commit_duration_ms: u64, attempt: usize, )

async fn on_commit_error( &self, err: &TransactionCommitError, attempt: usize, ) -> FdbResult<()>

fn on_closure_error(&self, err: &FdbError, attempt: usize)

fn on_error_duration(&self, duration_ms: u64, attempt: usize)

fn on_retry(&self, attempt: usize)

fn on_complete(&self)

impl<H: RunnerHooks + Sync> RunnerHooks for &H

fn on_attempt_start(&self, trx: &Transaction, attempt: usize)

fn before_commit( &self, trx: &Transaction, attempt: usize, ) -> impl Future<Output = FdbResult<()>> + Send

fn on_hook_error(&self, err: &FdbError, attempt: usize)

fn on_commit_success( &self, committed: &TransactionCommitted, commit_duration_ms: u64, attempt: usize, )

fn on_commit_error( &self, err: &TransactionCommitError, attempt: usize, ) -> impl Future<Output = FdbResult<()>> + Send

fn on_closure_error(&self, err: &FdbError, attempt: usize)

fn on_error_duration(&self, duration_ms: u64, attempt: usize)

fn on_retry(&self, attempt: usize)

fn on_complete(&self)

Implementors

impl RunnerHooks for MetricsHooks