Google is committed to advancing racial equity for Black communities. See how.

zx_object_wait_async

NAME

Subscribe for signals on an object.

SYNOPSIS

#include <zircon/syscalls.h>

zx_status_t zx_object_wait_async(zx_handle_t handle,
                                 zx_handle_t port,
                                 uint64_t key,
                                 zx_signals_t signals,
                                 uint32_t options);

DESCRIPTION

zx_object_wait_async() is a non-blocking syscall which causes packets to be enqueued on port when the object specified by handle has one or more of the specified signals asserted. Use zx_port_wait() to retrieve the packets.

handle points to the object that is to be watched for changes and must be a waitable object.

The options argument can be 0 or it can be ZX_WAIT_ASYNC_TIMESTAMP which causes the system to capture a timestamp when the wait triggered.

The signals argument is a bitmask indicating which signals on the object specified by handle will cause a packet to be enqueued. If any of those signals are asserted when zx_object_wait_async() is called or become asserted afterwards, a packet will be enqueued on port containing all of the currently-asserted signals (not just the ones listed in the signals argument). Once a packet has been enqueued the asynchronous waiting ends. No further packets will be enqueued. Note that signals are OR'd into the state maintained by the port thus you may see any combination of requested signals when zx_port_wait() returns.

zx_port_cancel() will terminate the operation and if a packet was in the queue on behalf of the operation, that packet will be removed from the queue.

If handle is closed, the operation will also be terminated, but packets already in the queue are not affected.

Packets generated via this syscall will have type set to ZX_PKT_TYPE_SIGNAL_ONE and the union is of type zx_packet_signal_t:

typedef struct zx_packet_signal {
    zx_signals_t trigger;
    zx_signals_t observed;
    uint64_t count;
    zx_time_t timestamp;       // depends on ZX_WAIT_ASYNC_TIMESTAMP
    uint64_t reserved1;
} zx_packet_signal_t;

trigger is the signals used in the call to zx_object_wait_async(), observed is the signals actually observed, and timestamp is clock-monotonic time when the object state transitioned to meet the trigger condition. If options does not include ZX_WAIT_ASYNC_TIMESTAMP the timestamp is reported as 0.

Use the zx_port_packet_t's key member to track what object this packet corresponds.

RIGHTS

handle must have ZX_RIGHT_WAIT.

port must be of type ZX_OBJ_TYPE_PORT and have ZX_RIGHT_WRITE.

RETURN VALUE

zx_object_wait_async() returns ZX_OK if the subscription succeeded.

ERRORS

ZX_ERR_INVALID_ARGS options is not 0 or ZX_WAIT_ASYNC_TIMESTAMP.

ZX_ERR_BAD_HANDLE handle is not a valid handle or port is not a valid handle.

ZX_ERR_WRONG_TYPE port is not a Port handle.

ZX_ERR_ACCESS_DENIED handle does not have ZX_RIGHT_WAIT or port does not have ZX_RIGHT_WRITE.

ZX_ERR_NOT_SUPPORTED handle is a handle that cannot be waited on.

ZX_ERR_NO_MEMORY Failure due to lack of memory. There is no good way for userspace to handle this (unlikely) error. In a future build this error will no longer occur.

NOTES

See signals for more information about signals and their terminology.

SEE ALSO