1# zx_object_wait_async
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7object_wait_async - subscribe for signals on an object
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_object_wait_async(zx_handle_t handle,
17                                 zx_handle_t port,
18                                 uint64_t key,
19                                 zx_signals_t signals,
20                                 uint32_t options);
21```
22
23## DESCRIPTION
24
25`zx_object_wait_async()` is a non-blocking syscall which causes packets to be
26enqueued on *port* when the specified condition is met.
27Use [`zx_port_wait()`] to retrieve the packets.
28
29*handle* points to the object that is to be watched for changes and must be a waitable object.
30
31The *options* argument can be either **ZX_WAIT_ASYNC_ONCE** or **ZX_WAIT_ASYNC_REPEATING**.
32
33In both cases, *signals* indicates which signals on the object specified by *handle*
34will cause a packet to be enqueued, and if **any** of those signals are asserted when
35`zx_object_wait_async()` is called, or become asserted afterwards, a packet will be
36enqueued on *port* containing all of the currently-asserted signals (not just the ones
37listed in the *signals* argument).
38
39In the case of **ZX_WAIT_ASYNC_ONCE**, once a packet has been enqueued the asynchronous
40waiting ends.  No further packets will be enqueued.
41
42In the case of **ZX_WAIT_ASYNC_REPEATING** the asynchronous waiting continues until
43canceled. If any of *signals* are asserted and a packet is not currently in *port*'s
44queue on behalf of this wait, a packet is enqueued. If a packet is already in the
45queue, the packet's *observed* field is updated to include all of the currently-asserted
46signals (without removing the existing signals).
47
48In either mode, [`zx_port_cancel()`] will terminate the operation and if a packet was
49in the queue on behalf of the operation, that packet will be removed from the queue.
50
51If *handle* is closed, the operation will also be terminated, but packets already
52in the queue are not affected.
53
54Packets generated via this syscall will have *type* set to either **ZX_PKT_TYPE_SIGNAL_ONE**
55or **ZX_PKT_TYPE_SIGNAL_REP**, and the union is of type `zx_packet_signal_t`:
56
57```
58typedef struct zx_packet_signal {
59    zx_signals_t trigger;
60    zx_signals_t observed;
61    uint64_t count;
62} zx_packet_signal_t;
63```
64
65*trigger* is the signals used in the call to `zx_object_wait_async()`, *observed* is the
66signals actually observed, and *count* is a per object defined count of pending operations. Use
67the `zx_port_packet_t`'s *key* member to track what object this packet corresponds to and
68therefore match *count* with the operation.
69
70## RIGHTS
71
72<!-- Updated by update-docs-from-abigen, do not edit. -->
73
74*handle* must have **ZX_RIGHT_WAIT**.
75
76*port* must be of type **ZX_OBJ_TYPE_PORT** and have **ZX_RIGHT_WRITE**.
77
78## RETURN VALUE
79
80`zx_object_wait_async()` returns **ZX_OK** if the subscription succeeded.
81
82## ERRORS
83
84**ZX_ERR_INVALID_ARGS**  *options* is not **ZX_WAIT_ASYNC_ONCE** or **ZX_WAIT_ASYNC_REPEATING**.
85
86**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle or *port* is not a valid handle.
87
88**ZX_ERR_WRONG_TYPE**  *port* is not a Port handle.
89
90**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_WAIT** or *port*
91does not have **ZX_RIGHT_WRITE**.
92
93**ZX_ERR_NOT_SUPPORTED**  *handle* is a handle that cannot be waited on.
94
95**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
96There is no good way for userspace to handle this (unlikely) error.
97In a future build this error will no longer occur.
98
99## NOTES
100
101See [signals](../signals.md) for more information about signals and their terminology.
102
103## SEE ALSO
104
105 - [`zx_object_wait_many()`]
106 - [`zx_object_wait_one()`]
107 - [`zx_port_cancel()`]
108 - [`zx_port_queue()`]
109 - [`zx_port_wait()`]
110
111<!-- References updated by update-docs-from-abigen, do not edit. -->
112
113[`zx_object_wait_many()`]: object_wait_many.md
114[`zx_object_wait_one()`]: object_wait_one.md
115[`zx_port_cancel()`]: port_cancel.md
116[`zx_port_queue()`]: port_queue.md
117[`zx_port_wait()`]: port_wait.md
118