Summary
Wait for signals on an object.
Declaration
#include <zircon/syscalls.h>
zx_status_t zx_object_wait_one(zx_handle_t handle,
zx_signals_t signals,
zx_time_t deadline,
zx_signals_t* observed);
Description
zx_object_wait_one()
is a blocking syscall that causes the caller to wait
until either the deadline passes or the object to which handle refers
asserts at least one signal specified by the bitmask signals. If
the object is already asserting at least one of the specified signals, the
wait ends immediately with ZX_OK
.
Upon return, if non-NULL, observed is a bitmap of all of the signals
asserted on the object. If one of the specified signals was asserted,
observed will be the set of signals asserted at the moment the specified
signal was first asserted. Otherwise, if deadline passes or handle is
closed, observed will contain the state of the object's signals at the time
the zx_object_wait_one
syscall completed.
The deadline parameter specifies a deadline with respect to
ZX_CLOCK_MONOTONIC
and will be automatically adjusted according to the job's
timer slack policy.
ZX_TIME_INFINITE
is a special value meaning wait forever.ZX_TIME_INFINITE_PAST
(or any value before the current time inZX_CLOCK_MONOTONIC
) will query the current value of the signal(s).
Rights
handle must have ZX_RIGHT_WAIT
.
Return value
zx_object_wait_one()
returns ZX_OK
if any of signals were active when
the call was made, or observed on the object before deadline passes.
In the event of ZX_ERR_TIMED_OUT
, observed may reflect state changes
that occurred after the deadline passed, but before the syscall returned.
In the event of ZX_ERR_CANCELED
, handle has been closed,
and observed will have the ZX_SIGNAL_HANDLE_CLOSED
bit set.
For any other return value, observed is undefined.
Errors
ZX_ERR_INVALID_ARGS
observed is an invalid pointer.
ZX_ERR_BAD_HANDLE
handle is not a valid handle.
ZX_ERR_ACCESS_DENIED
handle does not have ZX_RIGHT_WAIT
and may
not be waited upon.
ZX_ERR_CANCELED
handle was invalidated (e.g., closed) during the wait.
ZX_ERR_TIMED_OUT
The specified deadline passed before any of the specified
signals are observed on handle.
ZX_ERR_NOT_SUPPORTED
handle is a handle that cannot be waited on
(for example, a Port handle).
Notes
See signals for more information about signals and their terminology.