zx_port_wait
名称
port_wait —— 等待数据包到达端口
概要
#include <zircon/syscalls.h>
#include <zircon/syscalls/port.h>
zx_status_t zx_port_wait(zx_handle_t handle, zx_time_t deadline, zx_port_packet_t* packet);
描述
port_wait() 是一个阻塞系统调用,其功能是使调用者至少等到有一个来自端口的数据包可用。
调用返回时,如果成功,则packet将包含最早(以FIFO顺序)到达队列的数据包。
deadline标示何时停止等待数据包(相对于ZX_CLOCK_MONOTONIC时间)。如果在截止时间到来时没有数据包到达,则返回ZX_ERR_TIMED_OUT。传递ZX_TIME_INFINITE到deadline将导致永远等待,除非数据包已经在队列中可用于读取,否则过去的值将导致立刻超时返回。
与zx_object_wait_one() 和zx_object_wait_many() 不同的是,该调用(对于每个可用数据包)只释放一个等待线程,这使得端口可以由线程池提供服务。
数据包的来源有两个:调用port_queue() 手动排队的数据包,和当使用object_wait_async() 注册的对象改变状态时,内核所生成的数据包。这两种情况下,数据包始终为zx_port_packet_t类型:
struct zx_port_packet_t {
uint64_t key;
uint32_t type;
int32_t status;
union {
zx_packet_user_t user;
zx_packet_signal_t signal;
zx_packet_exception_t exception;
};
};
如果是通过port_queue() 生成的数据包,key是数据包中的键值,type被设置为ZX_PKT_TYPE_USER类型,并且联合字段的类型为zx_packet_user_t。
typedef union zx_packet_user {
uint64_t u64[4];
uint32_t u32[8];
uint16_t u16[16];
uint8_t c8[32];
} zx_packet_user_t;
port_queue() 的调用者控制上述结构体中的所有值。
如果是通过object_wait_async() 生成的数据包,key是传递给系统调用的键值,type被设置为ZX_PKT_TYPE_SIGNAL_ONE或ZX_PKT_TYPE_SIGNAL_REP类型,并且联合字段的类型为zx_packet_signal_t:
typedef struct zx_packet_signal {
zx_signals_t trigger;
zx_signals_t observed;
uint64_t count;
} zx_packet_signal_t;
对于ZX_WAIT_ASYNC_ONCE和ZX_WAIT_ASYNC_REPEATING类型而言:trigger是调用object_wait_async() 时使用的信号,count是每个对象定义的待处理操作数。使用key来跟踪此数据包对应的对象,从而使count与操作相匹配。
有关更多详细的信息,请参见object_wait_async。
权限
TODO(ZX-2399)
返回值
port_wait() 等待数据包成功出队列,并返回ZX_OK。
错误码
ZX_ERR_BAD_HANDLE:handle是无效句柄。
ZX_ERR_INVALID_ARGS:packet不是有效指针。
ZX_ERR_ACCESS_DENIED:handle没有ZX_RIGHT_WRITE权限,因此可能无法等待到数据包。 ZX_ERR_TIMED_OUT:deadline已过,且没有获取到数据包。