Struct OnSignals

pub struct OnSignals<'a, H: AsHandleRef> { /* private fields */ }

A future that completes when some set of signals become available on a Handle.

Implementations

impl<'a, H: AsHandleRef + 'a> OnSignals<'a, H>

pub fn new(handle: H, signals: Signals) -> Self

Creates a new OnSignals object which will receive notifications when any signals in signals occur on handle.

pub fn take_handle(self) -> H

where H: HandleBased,

Takes the handle.

pub fn extend_lifetime(self) -> LeakedOnSignals

This function allows the OnSignals object to live for the 'static lifetime, at the cost of disabling automatic cleanup of the port wait.

WARNING: Do not use unless you can guarantee that either:

• The future is not dropped before it completes, or
• The handle is dropped without creating additional OnSignals futures for it.

Creating an OnSignals calls zx_object_wait_async, which consumes a small amount of kernel resources. Dropping the OnSignals calls zx_port_cancel to clean up. But calling extend_lifetime disables this cleanup, since the zx_port_wait call requires a reference to the handle. The port registration can also be cleaned up by closing the handle or by waiting for the signal to be triggered. But if neither of these happens, the registration is leaked. This wastes kernel memory and the kernel will eventually kill your process to force a cleanup.

Note that OnSignals will not fire if the handle that was used to create it is dropped or transferred to another process.

Trait Implementations

impl<H: AsHandleRef> AsHandleRef for OnSignals<'_, H>

fn as_handle_ref(&self) -> HandleRef<'_>

Get a reference to the handle. One important use of such a reference is for object_wait_many.

fn raw_handle(&self) -> u32

Interpret the reference as a raw handle (an integer type). Two distinct handles will have different raw values (so it can perhaps be used as a key in a data structure).

fn signal_handle( &self, clear_mask: Signals, set_mask: Signals, ) -> Result<(), Status>

Set and clear userspace-accessible signal bits on an object. Wraps the zx_object_signal syscall.

fn wait_handle( &self, signals: Signals, deadline: Instant<MonotonicTimeline>, ) -> Result<Signals, Status>

Waits on a handle. Wraps the zx_object_wait_one syscall.

fn wait_async_handle( &self, port: &Port, key: u64, signals: Signals, options: WaitAsyncOpts, ) -> Result<(), Status>

Causes packet delivery on the given port when the object changes state and matches signals. zx_object_wait_async syscall.

fn get_name(&self) -> Result<Name, Status>

Get the Property::NAME property for this object.

fn set_name(&self, name: &Name) -> Result<(), Status>

Set the Property::NAME property for this object.

fn basic_info(&self) -> Result<HandleBasicInfo, Status>

Wraps the zx_object_get_info syscall for the ZX_INFO_HANDLE_BASIC topic.

fn count_info(&self) -> Result<HandleCountInfo, Status>

Wraps the zx_object_get_info syscall for the ZX_INFO_HANDLE_COUNT topic.

fn get_koid(&self) -> Result<Koid, Status>

Returns the koid (kernel object ID) for this handle.

impl<H: AsHandleRef> AsRef<H> for OnSignals<'_, H>

fn as_ref(&self) -> &H

Converts this type into a shared reference of the (usually inferred) input type.

impl<H: AsHandleRef> Debug for OnSignals<'_, H>

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

Formats the value using the given formatter.

impl<H: AsHandleRef> Drop for OnSignals<'_, H>

fn drop(&mut self)

Executes the destructor for this type.

impl<H: AsHandleRef + Unpin> Future for OnSignals<'_, H>

type Output = Result<Signals, Status>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.