zx_object_wait_async

英文原文快照

名称

object_wait_async —— 订阅对象发出信号

概要

  1. #include <zircon/syscalls.h>
  3. zx_status_t zx_object_wait_async(zx_handle_t handle,
  4.                                  zx_handle_t port,
  5.                                  uint64_t key,
  6.                                  zx_signals_t signals,
  7.                                  uint32_t options);

描述

object_wait_async() 是一个非阻塞的系统调用，当满足指定的条件时，系统会从port端口将数据包排入队列。 而后可使用port_wait() 来获取数据包。

handle指向要订阅其修改状态的对象，并且该对象必须是可等待的。

options参数可以是ZX_WAIT_ASYNC_ONCE或ZX_WAIT_ASYNC_REPEATING。

在这两种情况下，signals表示由handle指定的对象上的哪些信号会将数据包排入队列，并且如果在调用object_wait_async() 时将置位这些信号中任何之一，或在之后被置位，数据包都将从port端口上被排入队列中。

在包含ZX_WAIT_ASYNC_ONCE选项的情况下，一旦将数据包排入队列，异步等待立即结束，并且不会有其他数据包再排入队列。

在包含ZX_WAIT_ASYNC_REPEATING选项的情况下，将继续异步等待直至取消操作。 如果signals中的任何之一被置位，且数据包当前不在表示此等待的port队列中，则该数据包也将被排入队列。 如果数据包已经在队列中，则数据包的observed字段将被更新。

在上述任一模式下，port_cancel() 调用将取消操作。 如果该操作发生时数据包已在队列中，则该数据包将从队列中被删除。

如果关闭句柄，该订阅操作也将终止，但队列中已有的数据包不受影响。

有关每种类型的数据包及其语义的更多信息，请参见port_wait。

权限

TODO(ZX-2399)

返回值

如果订阅成功，则object_wait_async() 返回ZX_OK。

错误码

ZX_ERR_INVALID_ARGS：options不是ZX_WAIT_ASYNC_ONCE或ZX_WAIT_ASYNC_REPEATING。

ZX_ERR_BAD_HANDLE：handle是无效句柄或port是无效句柄。

ZX_ERR_WRONG_TYPE：port不是端口类型句柄。

ZX_ERR_ACCESS_DENIED：handle没有ZX_RIGHT_WAIT权限，或port没有ZX_RIGHT_WRITE权限。

ZX_ERR_NOT_SUPPORTED：handle是一个不可等待的句柄。

ZX_ERR_NO_MEMORY：由于内存不足导致的失败。 而用户空间无法处理这个（不太可能发生的）错误。 在将来的构建版本中，将不再出现此错误。

注释

有关信号及其术语的更多信息，请参见signals（英文原文）。

另见

port_cancel. port_queue. port_wait.