Struct zircon_object::signal::Futex
source · [−]pub struct Futex { /* private fields */ }
Expand description
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
sourceimpl Futex
impl Futex
sourcepub fn new(value: &'static AtomicI32) -> Arc<Self>
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.
sourcepub fn wait(
self: &Arc<Self>,
current_value: i32
) -> impl Future<Output = ZxResult>
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.
sourcepub fn wake(&self, wake_count: usize) -> usize
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.
sourcepub fn wait_with_owner(
self: &Arc<Self>,
current_value: i32,
thread: Option<Arc<Thread>>,
new_owner: Option<Arc<Thread>>
) -> impl Future<Output = ZxResult>
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 truenew_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 atvalue_ptr
.TIMED_OUT
: The thread was not woken before deadline passed.
sourcepub fn wake_single_owner(&self)
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.
sourcepub fn requeue(
&self,
current_value: i32,
wake_count: usize,
requeue_count: usize,
requeue_futex: &Arc<Futex>,
new_requeue_owner: Option<Arc<Thread>>,
check_value: bool
) -> ZxResult
pub fn requeue(
&self,
current_value: i32,
wake_count: usize,
requeue_count: usize,
requeue_futex: &Arc<Futex>,
new_requeue_owner: Option<Arc<Thread>>,
check_value: bool
) -> 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
sourceimpl KernelObject for Futex
impl KernelObject for Futex
sourcefn signal_set(&self, signal: Signal)
fn signal_set(&self, signal: Signal)
Assert signal
.
sourcefn signal_clear(&self, signal: Signal)
fn signal_clear(&self, signal: Signal)
Deassert signal
.
sourcefn signal_change(&self, clear: Signal, set: Signal)
fn signal_change(&self, clear: Signal, set: Signal)
Change signal status: first clear
then set
indicated bits. Read more
sourcefn add_signal_callback(&self, callback: SignalHandler)
fn add_signal_callback(&self, callback: SignalHandler)
Add callback
for signal status changes. Read more
sourcefn get_child(&self, _id: KoID) -> ZxResult<Arc<dyn KernelObject>>
fn get_child(&self, _id: KoID) -> ZxResult<Arc<dyn KernelObject>>
Attempt to find a child of the object with given KoID. Read more
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. Read more
sourcefn allowed_signals(&self) -> Signal
fn allowed_signals(&self) -> Signal
Get object’s allowed signals.
Auto Trait Implementations
impl !RefUnwindSafe for Futex
impl Send for Futex
impl Sync for Futex
impl Unpin for Futex
impl !UnwindSafe for Futex
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> CheckedAs for T
impl<T> CheckedAs for T
sourcefn checked_as<Dst>(self) -> Option<Dst> where
T: CheckedCast<Dst>,
fn checked_as<Dst>(self) -> Option<Dst> where
T: CheckedCast<Dst>,
Casts the value.
sourceimpl<Src, Dst> CheckedCastFrom<Src> for Dst where
Src: CheckedCast<Dst>,
impl<Src, Dst> CheckedCastFrom<Src> for Dst where
Src: CheckedCast<Dst>,
sourcefn checked_cast_from(src: Src) -> Option<Dst>
fn checked_cast_from(src: Src) -> Option<Dst>
Casts the value.
impl<T> Downcast for T where
T: Any,
impl<T> Downcast for T where
T: Any,
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
Convert Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
. Read more
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
Convert Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
. Read more
fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
Convert &Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s. Read more
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
Convert &mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s. Read more
sourceimpl<T> OverflowingAs for T
impl<T> OverflowingAs for T
sourcefn overflowing_as<Dst>(self) -> (Dst, bool) where
T: OverflowingCast<Dst>,
fn overflowing_as<Dst>(self) -> (Dst, bool) where
T: OverflowingCast<Dst>,
Casts the value.
sourceimpl<Src, Dst> OverflowingCastFrom<Src> for Dst where
Src: OverflowingCast<Dst>,
impl<Src, Dst> OverflowingCastFrom<Src> for Dst where
Src: OverflowingCast<Dst>,
sourcefn overflowing_cast_from(src: Src) -> (Dst, bool)
fn overflowing_cast_from(src: Src) -> (Dst, bool)
Casts the value.
sourceimpl<T> SaturatingAs for T
impl<T> SaturatingAs for T
sourcefn saturating_as<Dst>(self) -> Dst where
T: SaturatingCast<Dst>,
fn saturating_as<Dst>(self) -> Dst where
T: SaturatingCast<Dst>,
Casts the value.
sourceimpl<Src, Dst> SaturatingCastFrom<Src> for Dst where
Src: SaturatingCast<Dst>,
impl<Src, Dst> SaturatingCastFrom<Src> for Dst where
Src: SaturatingCast<Dst>,
sourcefn saturating_cast_from(src: Src) -> Dst
fn saturating_cast_from(src: Src) -> Dst
Casts the value.
sourceimpl<T> UnwrappedAs for T
impl<T> UnwrappedAs for T
sourcefn unwrapped_as<Dst>(self) -> Dst where
T: UnwrappedCast<Dst>,
fn unwrapped_as<Dst>(self) -> Dst where
T: UnwrappedCast<Dst>,
Casts the value.
sourceimpl<Src, Dst> UnwrappedCastFrom<Src> for Dst where
Src: UnwrappedCast<Dst>,
impl<Src, Dst> UnwrappedCastFrom<Src> for Dst where
Src: UnwrappedCast<Dst>,
sourcefn unwrapped_cast_from(src: Src) -> Dst
fn unwrapped_cast_from(src: Src) -> Dst
Casts the value.
sourceimpl<T> WrappingAs for T
impl<T> WrappingAs for T
sourcefn wrapping_as<Dst>(self) -> Dst where
T: WrappingCast<Dst>,
fn wrapping_as<Dst>(self) -> Dst where
T: WrappingCast<Dst>,
Casts the value.
sourceimpl<Src, Dst> WrappingCastFrom<Src> for Dst where
Src: WrappingCast<Dst>,
impl<Src, Dst> WrappingCastFrom<Src> for Dst where
Src: WrappingCast<Dst>,
sourcefn wrapping_cast_from(src: Src) -> Dst
fn wrapping_cast_from(src: Src) -> Dst
Casts the value.