Struct linux_futex::Futex
source · #[repr(transparent)]pub struct Futex<Scope> {
pub value: AtomicU32,
/* private fields */
}
Expand description
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§
source§impl<S: Scope> Futex<S>
impl<S: Scope> Futex<S>
sourcepub fn wait(&self, expected_value: u32) -> Result<(), WaitError>
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
.
sourcepub fn wait_for(
&self,
expected_value: u32,
timeout: Duration,
) -> Result<(), TimedWaitError>
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
.
sourcepub fn wake(&self, n: i32) -> i32
pub fn wake(&self, n: i32) -> i32
Wake up n
waiters.
Returns the number of waiters that were woken up.
sourcepub fn requeue(&self, n_wake: i32, to: &Futex<S>, n_requeue: i32) -> i32
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.
sourcepub fn cmp_requeue(
&self,
expected_value: u32,
n_wake: i32,
to: &Futex<S>,
n_requeue: i32,
) -> Result<i32, WrongValueError>
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.
sourcepub fn wait_bitset(
&self,
expected_value: u32,
bitset: u32,
) -> Result<(), WaitError>
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
.
sourcepub fn wait_bitset_until(
&self,
expected_value: u32,
bitset: u32,
timeout: impl Timeout,
) -> Result<(), TimedWaitError>
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
.
sourcepub fn wake_bitset(&self, n: i32, bitset: u32) -> i32
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.
sourcepub fn wake_op(&self, n: i32, second: &Futex<S>, op: OpAndCmp, n2: i32) -> i32
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.
sourcepub fn cmp_requeue_pi(
&self,
expected_value: i32,
to: &PiFutex<S>,
n_requeue: i32,
) -> Result<i32, TryAgainError>
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.
sourcepub fn wait_requeue_pi(
&self,
expected_value: u32,
second: &PiFutex<S>,
) -> Result<(), RequeuePiError>
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
.
sourcepub fn wait_requeue_pi_until(
&self,
expected_value: u32,
second: &PiFutex<S>,
timeout: impl Timeout,
) -> Result<(), TimedRequeuePiError>
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
.