Struct conquer_util::BackOff

pub struct BackOff { /* fields omitted */ }

A type for exponential back-off in tight loops.

In concurrent environments it can often be beneficial to back off from accessing shared variables in loops in order to reduce contention and improve performance for all participating threads by spinning for a short amount of time.

Methods

impl BackOff

pub const fn new() -> Self

Creates a new BackOff instance with a fixed exponential back-off strategy.

pub fn random() -> Self

Creates a new BackOff instance with a randomized exponential back-off strategy.

pub fn random_with_seed(seed: u64) -> Self

Creates a new BackOff instance with a randomized exponential back-off strategy using the given seed.

pub fn reset(&self)

Resets the BackOff instance to its initial state.

pub fn spin(&self)

Spins for a bounded number of steps

On CPUs that support such instructions, in each step the processor will be instructed to deliberately slow down, e.g. using the pause instruction on x86, which can also save energy.

Each invocation of this method exponentially increases the number of spin cycles until a point at which further spinning is no longer advisable and other strategies, such as yielding the current thread to the OS, should be preferred. From this point on, the number of spin cycles remains constant with each further invocation of spin.

Whether this point has been reached can be determined through the advise_yield method.

pub fn advise_yield(&self) -> bool

Returns true if further spinning is not advisable and other means such as voluntarily yielding the current thread could be more efficient.

Examples

Back-off exponentially until it is no longer advisable.

use conquer_util::BackOff;

let mut backoff = BackOff::new();
while !backoff.advise_yield() {
    backoff.spin();
}

Repedeatly check a condition and either back-off exponentially or yield the current thread, if the condition is not yet met.

use conquer_util::BackOff;


let mut backoff = BackOff::new();
while !cond {
    if backoff.advise_yield() {
        BackOff::yield_now();
    } else {
        backoff.spin();
    }
}

Notes

On an Intel(R) i5 with 2.60 GHz a full back-off cycle has been measured to take approximately 750 nanoseconds

pub fn spin_for(dur: Duration)

Spins at least for the specified dur.

If a very short duration is specified, this function may spin for a longer, platform-specific minimum time.

pub fn yield_now()

Cooperatively yields the current thread.

This is merely a convenience wrapper for thread::yield_now

Trait Implementations

impl Default for BackOff

fn default() -> Self

Returns the "default value" for a type.

impl Clone for BackOff

fn clone(&self) -> BackOff

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BackOff

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Display for BackOff

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.