摘要
创建一个采样器会话，返回一个 IOBuffer，其中包含为每个活跃 CPU 分配的缓冲区。
声明
#include <zircon/syscalls.h>
zx_status_t zx_sampler_create(zx_resource_t rsrc
uint64_t options,
zx_sampler_config_t* config,
size_t config_size;
zx_handle_t* iob_out);
说明
zx_sampler_create() 会初始化一个全局单例线程采样器，该采样器会将样本写入返回的 IOBuffer。返回的 iobuffer 会有一些区域数量等于系统调用时系统上的活动 CPU 数量。每个缓冲区的大小均与 config 中声明的大小相同。
参数 options 必须为 0。
参数 config 必须是 zx_sampler_config_t。
配置
typedef struct {
// How long an individual cpu core will wait in nanoseconds between
// taking each sample. The minimum period is ZX_SAMPLER_MIN_PERIOD (10000ns).
zx_duration_t period;
// The requested size of the region in bytes. The size will be
// rounded up to the next system page size boundary, as reported by
// zx_system_get_page_size(). Use `zx_object_get_info` with topic
// `ZX_INFO_IOB_REGIONS` on the returned handle to determine the
// actual size of each region.
size_t buffer_size;
// The requested discipline of the returned iobuffer. See below for
// valid disciplines.
uint64_t iobuffer_discipline;
} zx_sampler_config_t;
调用方可以请求使用商定的 IOBuffer 规范将样本写入返回的 IOBuffer 中。目前，有一个受支持的学科 ZX_IOB_DISCIPLINE_NONE (0) 的工作原理如下：
连接线程并开始采样后，每个 CPU 会将采样写入专用区域。采样将继续写入缓冲区，直到采样停止或缓冲区已满。
采样是通过读取线程的 PC 并尝试通过跟踪帧指针来遍历线程的回溯来读取的。
样本编写为 8 字节对齐的 FXT Large Blob with Metadata 记录，其中载荷包含从线程堆栈中采样的 PC。FXT 标头 0 表示没有其他数据。
为了安全地从缓冲区读取数据，读取操作应首先调用 zx_sampler_stop，它将停止会话并在没有写入其他样本时返回结果。然后，读取器可以使用 zx_vmar_map_iob 映射 IOBuffer 的每个区域并访问示例。
控制会话
采样器是一个全局单例，并且一次最多只有一个活跃的会话。可以通过将返回的 IOBuffer 传递给启动/停止/连接调用来控制会话。当返回的 IOBuffer 的最后一个句柄关闭时，会话将停止并销毁。
权限
debug_resource 必须具有基于 ZX_RSRC_SYSTEM_DEBUG_BASE 的资源种类 ZX_RSRC_KIND_SYSTEM。
错误
ZX_ERR_NOT_SUPPORTED kernel.enable-debugging-syscalls 未在内核命令行中设置为 true，或 experimental_thread_sampler_enabled 构建参数未设置为 true。
ZX_ERR_PERMISION_DENIED rsrc 不是基数为 ZX_RSRC_SYSTEM_DEBUG_BASE 的资源种类 ZX_RSRC_KIND_SYSTEM。
ZX_ERR_INVALID_ARGS
- options 不为 0
- 提供的 config 无效。如需了解预期的配置，请参阅 zx_sampler_config_t。