Struct zircon_object::signal::Futex

pub struct Futex { /* fields omitted */ }

A primitive for creating userspace synchronization tools.

SYNOPSIS

A futex is a Fast Userspace muTEX. It is a low level synchronization primitive which is a building block for higher level APIs such as pthread_mutex_t and pthread_cond_t. Futexes are designed to not enter the kernel or allocate kernel resources in the uncontested case.

Implementations

impl Futex

pub fn new(value: &'static AtomicI32) -> Arc<Self>

Create a new Futex.

The parameter value is the reference to an userspace AtomicI32. This reference is the information used in kernel to track what futex given threads are waiting on. The kernel does not currently modify the value of *value. It is up to userspace code to correctly atomically modify this value across threads in order to build mutexes and so on.

pub fn wait(
    self: &Arc<Self>,
    current_value: i32
) -> impl Future<Output = ZxResult>

Wait on a futex.

This atomically verifies that value_ptr still contains the value current_value and sleeps until the futex is made available by a call to wake.

See wait_with_owner for advanced usage and more details.

pub fn wake(&self, wake_count: usize) -> usize

Wake some number of threads waiting on a futex.

It wakes at most wake_count of the waiters that are waiting on this futex. Return the number of waiters that were woken up.

Ownership

The owner of the futex is set to nothing, regardless of the wake count.

pub fn owner(&self) -> Option<Arc<Thread>>

Get the owner of the futex.

pub fn wait_with_owner(
    self: &Arc<Self>,
    current_value: i32,
    thread: Option<Arc<Thread>>,
    new_owner: Option<Arc<Thread>>
) -> impl Future<Output = ZxResult>

Wait on a futex.

This atomically verifies that value_ptr still contains the value current_value and sleeps until the futex is made available by a call to wake.

SPURIOUS WAKEUPS

This implementation currently does not generate spurious wakeups.

Ownership

A successful call results in the owner of the futex being set to the thread referenced by the new_owner, or to nothing if it is None.

Errors

• INVALID_ARGS: One of the following is true
  • new_owner is currently a member of the waiters for this.
  • new_owner has not been started yet.
• BAD_STATE: current_value does not match the value at value_ptr.
• TIMED_OUT: The thread was not woken before deadline passed.

pub fn wake_single_owner(&self)

Wake exactly one thread from the futex wait queue.

If there is at least one thread to wake, the owner of the futex will be set to the thread which was woken. Otherwise, the futex will have no owner.

Ownership

If there is at least one thread to wake, the owner of the futex will be set to the thread which was woken. Otherwise, the futex will have no owner.

pub fn requeue(
    &self,
    current_value: i32,
    wake_count: usize,
    requeue_count: usize,
    requeue_futex: &Arc<Futex>,
    new_requeue_owner: Option<Arc<Thread>>
) -> ZxResult

Requeuing is a generalization of waking.

First, verifies that the value in current_value matches the value of the futex, and if not reports ZxError::BAD_STATE. After waking wake_count threads, requeue_count threads are moved from the original futex’s wait queue to the wait queue corresponding to another requeue_futex.

This requeueing behavior may be used to avoid thundering herds on wake.

Ownership

The owner of this futex is set to nothing, regardless of the wake count. The owner of the requeue_futex is set to the thread new_requeue_owner.

Trait Implementations

impl Debug for Futex

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

Formats the value using the given formatter.

impl KernelObject for Futex

fn id(&self) -> KoID

Get object’s KoID.

fn type_name(&self) -> &str

Get the name of the type of the kernel object.

fn name(&self) -> String

Get object’s name.

fn set_name(&self, name: &str)

Set object’s name.

fn signal(&self) -> Signal

Get the signal status.

fn signal_set(&self, signal: Signal)

Assert signal.

fn signal_clear(&self, signal: Signal)

Deassert signal.

fn signal_change(&self, clear: Signal, set: Signal)

Change signal status: first clear then set indicated bits.

fn add_signal_callback(&self, callback: SignalHandler)

Add callback for signal status changes.

fn get_child(&self, _id: KoID) -> ZxResult<Arc<dyn KernelObject>>

Attempt to find a child of the object with given KoID.

fn peer(&self) -> ZxResult<Arc<dyn KernelObject>>

Attempt to get the object’s peer.

fn related_koid(&self) -> KoID

If the object is related to another (such as the other end of a channel, or the parent of a job), returns the KoID of that object, otherwise returns zero.

fn allowed_signals(&self) -> Signal

Get object’s allowed signals.