Struct linux_futex::Futex

#[repr(transparent)]
pub struct Futex<Scope> {
    pub value: AtomicU32,
    /* private fields */
}

A Linux-specific fast user-space locking primitive.

Futex<Private> may only be used from the same address space (the same process) and is faster than a Futex<Shared>, which may be used accross address spaces (processes).

Fields

value: AtomicU32

Implementations

impl<S> Futex<S>

pub const fn new(value: u32) -> Self

Create a new Futex with an initial value.

impl<S: Scope> Futex<S>

pub fn wait(&self, expected_value: u32) -> Result<(), WaitError>

Wait until this futex is awoken by a wake call.

The thread will only be sent to sleep if the futex’s value matches the expected value. Otherwise, it returns directly with WaitError::WrongValue.

pub fn wait_for(
    &self,
    expected_value: u32,
    timeout: Duration
) -> Result<(), TimedWaitError>

Wait until this futex is awoken by a wake call, or until the timeout expires.

The thread will only be sent to sleep if the futex’s value matches the expected value. Otherwise, it returns directly with TimedWaitError::WrongValue.

If you want an absolute point in time as timeout, use wait_bitset_until instead, using a bitset of !0.

pub fn wake(&self, n: i32) -> i32

Wake up n waiters.

Returns the number of waiters that were woken up.

pub fn requeue(&self, n_wake: i32, to: &Futex<S>, n_requeue: i32) -> i32

Wake up n_wake waiters, and requeue up to n_requeue waiters to another futex.

Returns the number of waiters that were woken up.

pub fn cmp_requeue(
    &self,
    expected_value: u32,
    n_wake: i32,
    to: &Futex<S>,
    n_requeue: i32
) -> Result<i32, WrongValueError>

Wake up n_wake waiters, and requeue up to n_requeue waiters to another futex.

The operation will only execute if the futex’s value matches the expected value. Otherwise, it returns directly with a WrongValueError.

Returns the total number of waiters that were woken up or requeued to the other futex.

pub fn wait_bitset(
    &self,
    expected_value: u32,
    bitset: u32
) -> Result<(), WaitError>

Wait until this futex is awoken by a wake call matching a bitset.

• Calls to wake will match any bitset.
• Calls to wake_bitset will match if at least one 1-bit matches.

The thread will only be sent to sleep if the futex’s value matches the expected value. Otherwise, it returns directly with WaitError::WrongValue.

pub fn wait_bitset_until(
    &self,
    expected_value: u32,
    bitset: u32,
    timeout: impl Timeout
) -> Result<(), TimedWaitError>

Wait until this futex is awoken by a wake call matching a bitset, or until the timeout expires.

• Calls to wake will match any bitset.
• Calls to wake_bitset will match if at least one 1-bit matches.

The thread will only be sent to sleep if the futex’s value matches the expected value. Otherwise, it returns directly with TimedWaitError::WrongValue.

pub fn wake_bitset(&self, n: i32, bitset: u32) -> i32

Wake up n waiters matching a bitset.

• Waiters waiting using wait are always woken up, regardless of the bitset.
• Waiters waiting using wait_bitset are woken up if they match at least one 1-bit.

Returns the number of waiters that were woken up.

pub fn wake_op(&self, n: i32, second: &Futex<S>, op: OpAndCmp, n2: i32) -> i32

Wake up n waiters, and conditionally n2 waiters on another futex after modifying it.

This operation first applies an operation to the second futex while remembering its old value, then wakes up n waiters on the first futex, and finally wakes n2 waiters on the second futex if its old value matches a condition. This all happens atomically.

Returns the total number of waiters that were woken up on either futex.

pub fn cmp_requeue_pi(
    &self,
    expected_value: i32,
    to: &PiFutex<S>,
    n_requeue: i32
) -> Result<i32, TryAgainError>

Wake up one waiter, and requeue up to n_requeue to a PiFutex.

Only requeues waiters that are blocked by wait_requeue_pi or wait_requeue_pi_until. The PiFutex must be the same as the one the waiters are waiting to be requeued to.

The number of waiters to wake cannot be chosen and is always 1.

Returns the total number of waiters that were woken up or requeued to the other futex.

pub fn wait_requeue_pi(
    &self,
    expected_value: u32,
    second: &PiFutex<S>
) -> Result<(), RequeuePiError>

Wait until this futex is awoken after potentially being requeued to a PiFutex.

A call to cmp_requeue_pi will requeue this waiter to the PiFutex. The call must refer to the same PiFutex.

A call to wake (or wake_bitset) will wake this thread without requeueing. This results in an RequeuePiError::TryAgain.

pub fn wait_requeue_pi_until(
    &self,
    expected_value: u32,
    second: &PiFutex<S>,
    timeout: impl Timeout
) -> Result<(), TimedRequeuePiError>

Wait until this futex is awoken after potentially being requeued to a PiFutex, or until the timeout expires.

A call to cmp_requeue_pi will requeue this waiter to the PiFutex. The call must refer to the same PiFutex.

A call to wake (or wake_bitset) will wake this thread without requeueing. This results in an TimedRequeuePiError::TryAgain.

Trait Implementations

impl<S> Debug for Futex<S>

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

Formats the value using the given formatter.

impl<S> Default for Futex<S>

fn default() -> Self

Returns the “default value” for a type.