zx_clock_create

总结

创建一个新的时钟对象。

声明

#include <zircon/syscalls.h>

zx_status_t zx_clock_create(uint64_t options,
                            const void* args,
                            zx_handle_t* out);

权限

无。

说明

创建一个新的 zircon 时钟对象。如需查看时钟对象概览，请参阅时钟。

选项

为时钟对象定义了以下选项：

  • ZX_CLOCK_OPT_MONOTONIC：如果设置了此字段，则会创建一个保证绝不会反向运行的时钟对象。单调时钟必须始终向前移动。
  • ZX_CLOCK_OPT_CONTINUOUS：如果设置此参数，则会创建一个保证绝不会向前或向后跳跃的时钟。连续时钟只能使用频率调整来维护，并且根据定义是单调的。如果在未指定 ZX_CLOCK_OPT_MONOTONIC 选项的情况下尝试创建具有指定 ZX_CLOCK_OPT_CONTINUOUS 选项的时钟对象，系统将产生错误，系统将通过 ZX_ERR_INVALID_ARGS 发出信号。
  • ZX_CLOCK_OPT_AUTO_START：设置后，可创建一个自动为用户启动的时钟。您无需调用 zx_clock_update() 即可启动时钟。最初，时钟将是时钟单调的克隆，这意味着从时钟单调向新创建的合成时钟的内部转换是恒等函数。不过，已创建的时钟无需设置 ZX_CLOCK_OPT_MONOTONIC 或 ZX_CLOCK_OPT_CONTINUOUS 标志。创建后，用户仍可在由创建时指定的单调和连续属性、句柄权利和时钟的往返时间所定义的限制范围内更新时钟。

参数

在配置时钟（即往返时间）时，可以额外指定一个创建时间参数。如需详细了解往返时间，请参阅时钟。

为了配置退避时间，用户必须通过 args 参数将 zx_clock_create_args_v1_t 结构传递给 zx_clock_create 调用。此外，必须在 options 位中设置 ZX_CLOCK_ARGS_VERSION(1)。

例如，如果用户希望创建一个退避时间为 5500 的单调时钟，可以执行如下操作。

#include <zircon/syscalls.h>
#include <zircon/syscalls/clock.h>

zx_handle_t MakeAClock() {
  zx_clock_create_args_v1_t args;
  zx_handle_t the_clock;
  zx_status_t status;

  args.backstop_time = 5500;
  status = zx_clock_create(ZX_CLOCK_ARGS_VERSION(1) | ZX_CLOCK_OPT_MONOTONIC, &args, &the_clock);
  if (status != ZX_OK) {
    // Log the error
    return ZX_HANDLE_INVALID;
  }

  return the_clock;
}

用户无需提供参数结构。如果不需要显式退格，用户可以省略 options 参数中的版本位，而只为参数传递 nullptr。

返回值

成功后，通过 out 句柄返回 ZX_OK 以及一个新的时钟对象。系统会为新创建的时钟对象的句柄分配 ZX_RIGHT_READ、ZX_RIGHT_WRITE 和 ZX_RIGHT_SIGNAL 权限。

错误

  • ZX_ERR_INVALID_ARGS：指定了无效的选项标志，传递了错误的参数结构版本或指针，指定了 ZX_CLOCK_OPT_CONTINUOUS 但没有同时指定 ZX_CLOCK_OPT_MONOTONIC，或者自动启动的时钟的初始回停时间晚于当前时钟单调时间。
  • ZX_ERR_NO_MEMORY：因内存不足而失败。

另请参阅