zx_object_wait_async

摘要

訂閱物件的信號。

宣告

#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 因記憶體不足而失敗。 使用者空間無法妥善處理這種 (異常) 錯誤。 在日後的版本中不會再發生這個錯誤。

附註

如要進一步瞭解信號及相關術語，請參閱信號。

另請參閱