Struct Handle

pub struct Handle(/* private fields */);

Expand description

An owned and valid Zircon handle to a kernel object.

This type can be interconverted to and from more specific types. Those conversions are not enforced in the type system; attempting to use them will result in errors returned by the kernel. These conversions don’t change the underlying representation, but do change the type and what operations are available.

§Lifecycle

This type closes the handle it owns when dropped.

§Layout

Option<Handle> is guaranteed to have the same layout and bit patterns as zx_handle_t. Unlike many types in this crate it does not implement zerocopy traits because those are not appropriate for types with real Drop implementations.

Implementations§

§

impl Handle

pub unsafe fn from_raw(raw: u32) -> Option<Handle>

Take exclusive ownership over a raw handle.

§Safety

raw must either be ZX_HANDLE_INVALID or be a valid handle present in the current handle table that will not be closed by another owner.

pub unsafe fn from_raw_unchecked(raw: u32) -> Handle

Take exclusive ownership over a raw handle.

§Safety

raw must be a valid handle present in the current handle table that will not be closed by another owner.

pub fn check_raw_valid(raw: u32) -> Result<(), Status>

Wraps the zx_handle_check_valid syscall.

Note that this does not guarantee that the handle is safe to pass to Handle::from_raw in cases where another function may close the handle.

pub const fn raw_handle(&self) -> u32

Returns the raw handle’s integer value.

pub fn into_raw(self) -> u32

Return the raw handle’s integer value without closing it when self is dropped.

pub fn duplicate(&self, rights: Rights) -> Result<Handle, Status>

Wraps the zx_handle_duplicate syscall.

pub fn replace(self, rights: Rights) -> Result<Handle, Status>

Wraps the zx_handle_replace syscall.

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

Wraps the zx_object_signal syscall.

pub fn wait_one( &self, signals: Signals, deadline: Instant<MonotonicTimeline>, ) -> WaitResult

Wraps the zx_object_wait_one syscall.

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

Wraps the zx_object_wait_async syscall.

pub fn wait_item(&self, signals: Signals) -> WaitItem<'_>

Return a WaitItem for this handle and signals that can be used with [object_wait_many].

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

Get the Property::NAME property for this object.

Wraps a call to the zx_object_get_property syscall for the ZX_PROP_NAME property.

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

Set the Property::NAME property for this object.

The name’s length must be less than sys::ZX_MAX_NAME_LEN, i.e. name.to_bytes_with_nul().len() <= sys::ZX_MAX_NAME_LEN, or Err(Status::INVALID_ARGS) will be returned.

Wraps a call to the zx_object_get_property syscall for the ZX_PROP_NAME property.

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

Wraps the zx_object_get_info syscall for the ZX_INFO_HANDLE_BASIC topic.

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

Wraps the zx_object_get_info syscall for the ZX_INFO_HANDLE_COUNT topic.

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

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

Trait Implementations§

§

impl AsHandleRef for Handle

§

fn as_handle_ref(&self) -> Unowned<'_, NullableHandle>

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

§

impl Debug for Handle

§

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

Formats the value using the given formatter. Read more

§

impl Drop for Handle

§

fn drop(&mut self)

Executes the destructor for this type. Read more

Source §

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

§