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.

Implementations

impl BackOff

pub const fn new() -> Self

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

pub fn spin_once()

Spin once.

This is a convenience wrapper for spin_loop_hint, but will never compile to only a nop on platforms, that don't offer a wait-like CPU instruction, but will instead result in an empty function call.

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() {
        std::thread::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

impl BackOff

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 value.

impl BackOff

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 a convenience wrapper for thread::yield_now

Trait Implementations

impl Clone for BackOff

pub fn clone(&self) -> BackOff

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for BackOff

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BackOff

pub fn default() -> Self

Returns the "default value" for a type.

impl Display for BackOff

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.