摘要
訂閱物件的信號。
宣告
#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() 是無阻斷的系統呼叫，當 handle 指定的物件有一個或多個指定的 signal 時，會導致封包在 port 上排入佇列。使用 zx_port_wait() 擷取封包。
handle 指向要觀察變更的物件，且必須為可等待的物件。
options 引數可以是 0，也可以是下列一或多個選項：
- ZX_WAIT_ASYNC_TIMESTAMP，會在系統觸發等待時擷取單調時間戳記。
- ZX_WAIT_ASYNC_BOOT_TIMESTAMP，會在等待觸發時，讓系統擷取啟動時間戳記。
- ZX_WAIT_ASYNC_EDGE 會導致通訊埠不在
zx_object_wait_async()呼叫期間啟用信號的封包佇列。
請注意，傳入 ZX_WAIT_ASYNC_TIMESTAMP 和 ZX_WAIT_ASYNC_BOOT_TIMESTAMP 無效，會傳回 ZX_ERR_INVALID_ARGS。
signals 引數是一個位元遮罩，指出由 handle 指定的物件上的哪些信號會將封包排入佇列。
如果沒有 ZX_WAIT_ASYNC_EDGE，當 zx_object_wait_async() 呼叫或之後變為啟用時，如果 signals 中信號的 any 為啟用狀態，就會將封包排入 port 的佇列。
在 ZX_WAIT_ASYNC_EDGE 中，只有在 signals 中有一或多個信號從停用轉為啟用時，封包才會排入 port 的佇列。使用這個選項時，請注意，在呼叫 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() 會終止所有非同步等待作業，這些作業使用具有指定鍵的句柄和端口。此外，這些作業產生的佇列中，任何封包都會從佇列中移除。
如果「handle」關閉，與其相關聯的作業也會終止，但佇列中已存在的封包不會受到影響。
透過這個系統呼叫產生的封包會將類型設為 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_instant_mono_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 在兩種情況下會傳回此值。第一個是如果 options 有 ZX_WAIT_ASYNC_TIMESTAMP、ZX_WAIT_ASYNC_BOOT_TIMESTAMP 和 ZX_WAIT_ASYNC_EDGE 集合以外的位元，如果同時設定 ZX_WAIT_ASYNC_TIMESTAMP 和 ZX_WAIT_ASYNC_BOOT_TIMESTAMP，則秒數為秒。
ZX_ERR_BAD_HANDLE handle 不是有效的帳號代碼，或 port 不是有效的帳號。
ZX_ERR_WRONG_TYPE port 不是 Port 句柄。
ZX_ERR_ACCESS_DENIED 句柄沒有 ZX_RIGHT_WAIT，或是通訊埠沒有 ZX_RIGHT_WRITE。
ZX_ERR_NOT_SUPPORTED handle 是無法等待的 handle。
ZX_ERR_NO_MEMORY 記憶體不足導致失敗。使用者空間沒有適當的方式來處理這個 (不太可能發生的) 錯誤。日後的版本將不會再發生這個錯誤。
附註
如要進一步瞭解信號和相關術語，請參閱「信號」。