摘要
建立取樣器工作階段，傳回 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 區域數量會等於系統上的有效 cpus 數量。每個緩衝區都是您在 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 都會將樣本寫入專屬區域。系統會持續將樣本寫入緩衝區，直到取樣停止或緩衝區已滿為止。
讀取樣本時，系統會讀取執行緒的電腦，並嘗試依照影格指標檢查執行緒的反向追蹤。
樣本會以 8 個位元組對齊 FXT Large Blob 與中繼資料記錄，其中酬載包含從執行緒堆疊取樣的電腦。0 的 FXT 標頭表示沒有其他資料。
如要安全地讀取緩衝區中的資料，讀取作業必須先呼叫 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
- 提供的設定無效。如需預期的設定，請參閱 zx_sampler_config_t。