zx_object_wait_many

英文原文快照

名称

object_wait_many —— 等待多个对象上发出的信号

概要

  1. #include <zircon/syscalls.h>
  3. zx_status_t zx_object_wait_many(zx_wait_item_t* items, size_t count, zx_time_t deadline);
  5. typedef struct {
  6.     zx_handle_t handle;
  7.     zx_signals_t waitfor;
  8.     zx_signals_t pending;
  9. } zx_wait_item_t;

描述

object_wait_many() 是一个阻塞式的系统调用，它的目的是使调用者等待直到截止时刻deadline到来，或者指定的信号中至少有一个被相关句柄所引用的对象置位。 如果对象已经在至少一个指定信号上置位，则等待立即返回。

调用者必须在items数组中提供count个zx_wait_item_ts类型的结构体，其中每一项包含句柄和信号位掩码以用于等待操作。

deadline参数指定了相对于ZX_CLOCK_MONOTONIC的截止时刻。 而ZX_TIME_INFINITE参数是一个特殊的值，它表示永远等待。

调用返回时，items的pending字段用表示每个项的待处理信号的位图(bitmap)来填充。

如果对象的状态被另一个线程或进程修改，则items中的pending信号可能无法反映对象信号的实际状态。 （例如，一旦队列中的最后一条消息被读取，通道就会停止在ZX_CHANNEL_READABLE上置位）

可以用于等待的最大项数为ZX_WAIT_MANY_MAX_ITEMS，即为8。 如果需要等待更多对象，请使用端口。

权限

TODO(ZX-2399)

返回值

如果在deadline截止时刻到来之前，在其各自的对象上观察到任何waitfor信号中的一个，则object_wait_many() 返回ZX_OK。

即使调用返回ZX_ERR_TIMED_OUT，items也会反映出在截止时刻到来之后但在系统调用返回之前发生的状态更改。

如果返回ZX_ERR_CANCELED，表示一个或多个等待的句柄已关闭，并且这些项的pending字段将置ZX_SIGNAL_HANDLE_CLOSED位。

对于任何其他返回值，items的pending字段均是未定义的。

错误码

ZX_ERR_INVALID_ARGS：items是无效指针。

ZX_ERR_OUT_OF_RANGE：count大于ZX_WAIT_MANY_MAX_ITEMS。 ZX_ERR_BAD_HANDLE：items其中一项包含无效句柄。

ZX_ERR_ACCESS_DENIED：提供的handles中一个或多个没有ZX_RIGHT_WAIT权限，因此可能无法等待。

ZX_ERR_CANCELED：在等待期间，提供的handles中一个或多个变成无效状态（比如关闭）。

ZX_ERR_TIMED_OUT：指定的截止时刻超时发生在，任何指定句柄上等待到任何指定信号之前。

ZX_ERR_NOT_SUPPORTED：items其中一项包含不可等待的句柄（例如端口句柄等）。

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

BUGS

参数名称pending应该更合适被称作observed。

另见

object_wait_many, object_wait_one.