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_BOOT：设置后，会创建一个引用为启动时间轴的时钟对象。
  • ZX_CLOCK_OPT_MONOTONIC：如果设置，则会创建一个保证绝不会向后运行的时钟对象。单调时钟必须始终向前推进。
  • ZX_CLOCK_OPT_CONTINUOUS：设置后，会创建一个保证永远不会向前或向后跳转的时钟。连续时钟只能使用频率调整进行维护，并且从定义上讲，它们也是单调的。尝试创建指定了 ZX_CLOCK_OPT_CONTINUOUS 选项但未指定 ZX_CLOCK_OPT_MONOTONIC 选项的时钟对象是错误行为，系统会发出 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 参数中省略版本位，只需为 args 传递 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 因内存不足而失败。

另请参阅