摘要
訂閱物件的信號。
宣告
#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()
是會造成封包傳輸的非阻斷系統呼叫
當帳號代碼指定的物件有一或多個
指定的信號。使用 zx_port_wait()
擷取封包。
handle 指向要觀察變更的物件,且必須為可等待的物件。
options 引數可以是 0 或一或多個
- ZX_WAIT_ASYNC_TIMESTAMP,會讓系統擷取時間戳記 等待觸發的時間
- ZX_WAIT_ASYNC_EDGE 會導致通訊埠不會將封包排入已啟用信號的佇列
指定回應。
zx_object_wait_async()
signals 引數是位元遮罩,用於指出物件的哪些信號 系統會透過 handle 指定,將封包排入佇列。
沒有 ZX_WAIT_ASYNC_EDGE
,如果信號中有 any
的信號已啟用
呼叫 zx_object_wait_async()
或之後啟用時,封包
新增至通訊埠的佇列。
如果使用 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()
會終止所有含
處理常式和通訊埠具有指定金鑰。此外,這個伺服器中的任何封包
系統會從佇列中移除這些作業產生的佇列。
如果 handle 關閉,與其相關聯的作業也會 但已在佇列中的封包不會受到影響。
透過這個 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;
觸發條件是呼叫 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
handle 不是有效的帳號代碼,或 port 不是有效的帳號。
ZX_ERR_WRONG_TYPE
通訊埠並非通訊埠控制代碼。
ZX_ERR_ACCESS_DENIED
處理常式沒有 ZX_RIGHT_WAIT
或 port
沒有 ZX_RIGHT_WRITE
。
ZX_ERR_NOT_SUPPORTED
handle 是一個無法等待的帳號代碼。
ZX_ERR_NO_MEMORY
因記憶體不足而失敗。
使用者空間無法妥善處理這種 (異常) 錯誤。
在日後的版本中不會再發生這個錯誤。
附註
如要進一步瞭解信號及相關術語,請參閱信號。