摘要
訂閱物件的信號。
宣告
#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);
說明
zx_object_wait_async() 是非阻塞的系統呼叫，當處理常式指定的物件具有一或多個指定的信號時，會導致封包在 port 上排入佇列。使用 zx_port_wait() 擷取封包。
handle 指向要監控變更的物件，而且必須是可等候的物件。
options 引數可以是 0，也可以是一或多個
- ZX_WAIT_ASYNC_TIMESTAMP，導致系統在觸發等待事件時擷取時間戳記。
- ZX_WAIT_ASYNC_EDGE 會導致通訊埠不要將
zx_object_wait_async()呼叫當下已啟用的信號封包排入佇列。
signals 引數是一個位元遮罩，用於指出 handle 指定物件上有哪些信號會導致封包排入佇列。
如果沒有 ZX_WAIT_ASYNC_EDGE，當在呼叫 zx_object_wait_async() 或之後變為啟用時，信號中的 any 信號為有效狀態，系統就會在通訊埠中將封包排入佇列。
使用 ZX_WAIT_ASYNC_EDGE 時，只有在信號中的一或多個信號從停用中轉換到有效狀態之後，封包才會在通訊埠上排入佇列。使用這個選項時，應在呼叫 zx_object_wait_async() 完成前，注意閒置信號會意外啟用。在這種情況下，轉換可能會錯過，系統不會將任何封包排入通訊埠佇列。例如，通常在執行非阻塞式 I/O 之前，會一直使用到信號失效為止，確保後續從無效轉換變成使用中會導致封包排入佇列。
封包排入佇列時，會包含所有目前已宣告的信號 (而不只是 signals 引數中列出的信號)。封包排入佇列後
非同步等待就會結束。其他封包將不會排入佇列。請注意，信號為 OR 位於通訊埠維護的狀態，因此在 zx_port_wait() 傳回時，您會看到任何要求的信號組合。
每次呼叫 zx_object_wait_async() 都會建立新的非同步等待作業 (或觀測器)。系統不會以任何方式簡化這些作業。也就是說，如果使用相同引數兩次呼叫 zx_object_wait_async()，系統將建立兩項作業。此外，如果宣告的信號與這些作業相符，系統會將兩個封包排入佇列，且每項作業各一個。
每個通訊埠可執行的作業數量有限。如果超過限制，工作政策例外狀況 (ZX_EXCP_POLICY_CODE_PORT_TOO_MANY_OBSERVERS) 就會由超過限制的程序提出。
zx_port_cancel() 會使用具有指定金鑰的處理常式和通訊埠，終止所有非同步等待作業。此外，這些作業產生的佇列中的所有封包都會從佇列中移除。
如果「處理程式」已關閉，相關聯的作業也會一併終止，但已在佇列中的封包則不受影響。
透過這個 syscall 產生的封包會將 type 設為 ZX_PKT_TYPE_SIGNAL_ONE，且聯集為 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」是呼叫 zx_object_wait_async() 時使用的信號，「觀察」是指實際觀察的信號，而 timestamp 是物件狀態轉換為符合觸發條件的條件時維持時鐘單調時間。如果選項不包含 ZX_WAIT_ASYNC_TIMESTAMP，時間戳記會回報為 0。
使用 zx_port_packet_t 的 金鑰 成員追蹤這個封包對應的物件。
權限
handle 必須具有 ZX_RIGHT_WAIT。
port 必須為類型 ZX_OBJ_TYPE_PORT 且具有 ZX_RIGHT_WRITE。
傳回值
如果訂閱成功，zx_object_wait_async() 會傳回 ZX_OK。
錯誤
ZX_ERR_INVALID_ARGS 選項有設定 ZX_WAIT_ASYNC_TIMESTAMP 和 ZX_WAIT_ASYNC_EDGE 以外的位元。
ZX_ERR_BAD_HANDLE 帳號代碼不是有效的控制代碼，或 port 不是有效的控制代碼。
ZX_ERR_WRONG_TYPE port 不是通訊埠控制代碼。
ZX_ERR_ACCESS_DENIED 處理常式沒有 ZX_RIGHT_WAIT 或通訊埠沒有 ZX_RIGHT_WRITE，
ZX_ERR_NOT_SUPPORTED 帳號代碼是無法等待的控制代碼。
ZX_ERR_NO_MEMORY 因記憶體不足而失敗。使用者空間無法以任何方式處理這個錯誤 (極可能) 錯誤。日後的建構作業不會再發生這個錯誤。
附註
如要進一步瞭解信號及其術語，請參閱信號。