1# zx_object_wait_many
2
3## NAME
4
5object_wait_many - wait for signals on multiple objects
6
7## SYNOPSIS
8
9```
10#include <zircon/syscalls.h>
11
12zx_status_t zx_object_wait_many(zx_wait_item_t* items, size_t count, zx_time_t deadline);
13
14typedef struct {
15    zx_handle_t handle;
16    zx_signals_t waitfor;
17    zx_signals_t pending;
18} zx_wait_item_t;
19```
20
21## DESCRIPTION
22
23**object_wait_many**() is a blocking syscall which causes the caller to
24wait until either the *deadline* passes or at least one of the specified
25signals is asserted by the object to which the associated handle refers.
26If an object is already asserting at least one of the specified signals,
27the wait ends immediately.
28
29The caller must provide *count* zx_wait_item_ts in the *items* array,
30containing the handle and signals bitmask to wait for for each item.
31
32The *deadline* parameter specifies a deadline with respect to
33**ZX_CLOCK_MONOTONIC**.  **ZX_TIME_INFINITE** is a special value meaning wait
34forever.
35
36Upon return, the *pending* field of *items* is filled with bitmaps indicating
37which signals are pending for each item.
38
39The *pending* signals in *items* may not reflect the actual state of the object's
40signals if the state of the object was modified by another thread or
41process.  (For example, a Channel ceases asserting **ZX_CHANNEL_READABLE**
42once the last message in its queue is read).
43
44The maximum number of items that may be waited upon is **ZX_WAIT_MANY_MAX_ITEMS**,
45which is 8.  To wait on more things at once use [Ports](../objects/port.md).
46
47## RIGHTS
48
49TODO(ZX-2399)
50
51## RETURN VALUE
52
53**object_wait_many**() returns **ZX_OK** if any of *waitfor* signals were
54observed on their respective object before *deadline* passed.
55
56In the event of **ZX_ERR_TIMED_OUT**, *items* may reflect state changes
57that occurred after the deadline pased, but before the syscall returned.
58
59In the event of **ZX_ERR_CANCELED**, one or more of the items being waited
60upon have had their handles closed, and the *pending* field for those items
61will have the **ZX_SIGNAL_HANDLE_CLOSED** bit set.
62
63For any other return value, the *pending* fields of *items* are undefined.
64
65## ERRORS
66
67**ZX_ERR_INVALID_ARGS**  *items* isn't a valid pointer.
68
69**ZX_ERR_OUT_OF_RANGE**  *count* is greater than **ZX_WAIT_MANY_MAX_ITEMS**.
70
71**ZX_ERR_BAD_HANDLE**  one of *items* contains an invalid handle.
72
73**ZX_ERR_ACCESS_DENIED**  One or more of the provided *handles* does not
74have **ZX_RIGHT_WAIT** and may not be waited upon.
75
76**ZX_ERR_CANCELED**  One or more of the provided *handles* was invalidated
77(e.g., closed) during the wait.
78
79**ZX_ERR_TIMED_OUT**  The specified deadline passed before any of the specified signals are
80observed on any of the specified handles.
81
82**ZX_ERR_NOT_SUPPORTED**  One of the *items* contains a handle that cannot
83be waited one (for example, a Port handle).
84
85**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
86There is no good way for userspace to handle this (unlikely) error.
87In a future build this error will no longer occur.
88
89## BUGS
90
91*pending* more properly should be called *observed*.
92
93## SEE ALSO
94
95[object_wait_many](object_wait_many.md),
96[object_wait_one](object_wait_one.md).
97