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