模块 Runtime_events

module Runtime_events: sig .. end

运行时事件 - 基于环形缓冲区的运行时跟踪

此模块使用户能够启用和订阅来自垃圾收集器和 OCaml 运行时其他部分的跟踪事件。这对于诊断或性能监控很有用。此模块可用于异步订阅当前进程或外部进程的事件。

启用后（通过设置 OCAML_RUNTIME_EVENTS_START 环境变量或调用 Runtime_events.start），将创建一个包含进程 pid 和扩展名 .events 的文件。默认情况下，此文件位于当前目录中，但可以通过 OCAML_RUNTIME_EVENTS_DIR 环境变量覆盖。每个域在较大文件的一个部分中维护自己的环形缓冲区，并在其中发出事件。

此外，runtime_events.h 中还有一组 C API，可以启用对当前进程的零影响监控或其他语言的绑定。

运行时事件系统的行为可以通过以下环境变量控制

如果设置了 OCAML_RUNTIME_EVENTS_START，则会在 OCaml 运行时初始化过程中启动运行时事件系统。

OCAML_RUNTIME_EVENTS_DIR 设置运行时事件环形缓冲区所在的目录。如果不存在，则使用程序的工作目录。

如果设置了 OCAML_RUNTIME_EVENTS_PRESERVE，则会阻止 OCaml 运行时在终止时删除其环形缓冲区。如果监视运行时间非常短的程序，这很有帮助。

type runtime_counter =

`\|`	`EV_C_FORCE_MINOR_ALLOC_SMALL`
`\|`	`EV_C_FORCE_MINOR_MAKE_VECT`
`\|`	`EV_C_FORCE_MINOR_SET_MINOR_HEAP_SIZE`
`\|`	`EV_C_FORCE_MINOR_MEMPROF`
`\|`	`EV_C_MINOR_PROMOTED`
`\|`	`EV_C_MINOR_ALLOCATED`
`\|`	`EV_C_REQUEST_MAJOR_ALLOC_SHR`
`\|`	`EV_C_REQUEST_MAJOR_ADJUST_GC_SPEED`
`\|`	`EV_C_REQUEST_MINOR_REALLOC_REF_TABLE`
`\|`	`EV_C_REQUEST_MINOR_REALLOC_EPHE_REF_TABLE`
`\|`	`EV_C_REQUEST_MINOR_REALLOC_CUSTOM_TABLE`
`\|`	`EV_C_MAJOR_HEAP_POOL_WORDS`	`(*`	域的主要堆池中的总字数。这是每个池中未分配和活动字的总和。自 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_POOL_LIVE_WORDS`	`(*`	域的主要堆池中当前的活动字数。自 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_LARGE_WORDS`	`(*`	域的主要堆大分配的总字数。大分配是指大于最大池大小的分配。自 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_POOL_FRAG_WORDS`	`(*`	域的主要堆池中因碎片而损失的字数。这是由于没有与分配大小完全匹配的池，并且需要使用更大尺寸的池造成的。自 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_POOL_LIVE_BLOCKS`	`(*`	域的主要堆池的活动块数。自 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_LARGE_BLOCKS`	`(*`	域的主要堆大分配的活动块数。自 5.1	`*)`

运行时发出的计数器事件的类型。

type runtime_phase =

`\|`	`EV_EXPLICIT_GC_SET`
`\|`	`EV_EXPLICIT_GC_STAT`
`\|`	`EV_EXPLICIT_GC_MINOR`
`\|`	`EV_EXPLICIT_GC_MAJOR`
`\|`	`EV_EXPLICIT_GC_FULL_MAJOR`
`\|`	`EV_EXPLICIT_GC_COMPACT`
`\|`	`EV_MAJOR`
`\|`	`EV_MAJOR_SWEEP`
`\|`	`EV_MAJOR_MARK_ROOTS`
`\|`	`EV_MAJOR_MARK`
`\|`	`EV_MINOR`
`\|`	`EV_MINOR_LOCAL_ROOTS`
`\|`	`EV_MINOR_FINALIZED`
`\|`	`EV_EXPLICIT_GC_MAJOR_SLICE`
`\|`	`EV_FINALISE_UPDATE_FIRST`
`\|`	`EV_FINALISE_UPDATE_LAST`
`\|`	`EV_INTERRUPT_REMOTE`
`\|`	`EV_MAJOR_EPHE_MARK`
`\|`	`EV_MAJOR_EPHE_SWEEP`
`\|`	`EV_MAJOR_FINISH_MARKING`
`\|`	`EV_MAJOR_GC_CYCLE_DOMAINS`
`\|`	`EV_MAJOR_GC_PHASE_CHANGE`
`\|`	`EV_MAJOR_GC_STW`
`\|`	`EV_MAJOR_MARK_OPPORTUNISTIC`
`\|`	`EV_MAJOR_SLICE`
`\|`	`EV_MAJOR_FINISH_CYCLE`
`\|`	`EV_MINOR_CLEAR`
`\|`	`EV_MINOR_FINALIZERS_OLDIFY`
`\|`	`EV_MINOR_GLOBAL_ROOTS`
`\|`	`EV_MINOR_LEAVE_BARRIER`
`\|`	`EV_STW_API_BARRIER`
`\|`	`EV_STW_HANDLER`
`\|`	`EV_STW_LEADER`
`\|`	`EV_MAJOR_FINISH_SWEEPING`
`\|`	`EV_MINOR_FINALIZERS_ADMIN`
`\|`	`EV_MINOR_REMEMBERED_SET`
`\|`	`EV_MINOR_REMEMBERED_SET_PROMOTE`
`\|`	`EV_MINOR_LOCAL_ROOTS_PROMOTE`
`\|`	`EV_DOMAIN_CONDITION_WAIT`
`\|`	`EV_DOMAIN_RESIZE_HEAP_RESERVATION`
`\|`	`EV_COMPACT`
`\|`	`EV_COMPACT_EVACUATE`
`\|`	`EV_COMPACT_FORWARD`
`\|`	`EV_COMPACT_RELEASE`

运行时发出的跨度事件的类型。

type lifecycle =

`\|`	`EV_RING_START`
`\|`	`EV_RING_STOP`
`\|`	`EV_RING_PAUSE`
`\|`	`EV_RING_RESUME`
`\|`	`EV_FORK_PARENT`
`\|`	`EV_FORK_CHILD`
`\|`	`EV_DOMAIN_SPAWN`
`\|`	`EV_DOMAIN_TERMINATE`

环本身的生命周期事件。

val lifecycle_name : lifecycle -> string

返回给定生命周期事件类型的字符串表示形式。

val runtime_phase_name : runtime_phase -> string

返回给定运行时阶段事件类型的字符串表示形式。

val runtime_counter_name : runtime_counter -> string

返回给定运行时计数器类型的字符串表示形式。

type cursor

使用时使用的游标类型。

module Timestamp: sig .. end

module Type: sig .. end

module User: sig .. end

module Callbacks: sig .. end

val start : unit -> unit

start () 如果尚未启动，则启动运行时中的事件收集。

可以通过使用 create_cursor 创建游标并提供一组回调函数来使用事件，这些回调函数将针对每种类型的事件调用。

val pause : unit -> unit

pause () 将暂停运行时中的事件收集。如果程序已调用 Runtime_events.start () 或已设置 OCAML_RUNTIME_EVENTS_START 环境变量，则会收集跟踪。

val resume : unit -> unit

resume () 将恢复运行时中的事件收集。如果程序已调用 Runtime_events.start () 或已设置 OCAML_RUNTIME_EVENTS_START 环境变量，则会收集跟踪。

val create_cursor : (string * int) option -> cursor

create_cursor path_pid 创建一个游标以从 runtime_events 读取。可以为进程内和进程外的 runtime_events 创建游标。runtime_events 环形缓冲区可以在任何时间点有多个游标从中读取，并且程序可以同时打开多个游标（例如，如果多个使用者需要不同的事件集）。如果 path_pid 为 None，则为当前进程创建一个游标。否则，该对包含一个字符串 path，指向包含 pid.events 文件的目录，以及一个整数 pid，用于监视外部进程的 runtime_events。

val free_cursor : cursor -> unit

释放先前创建的 runtime_events 游标。

val read_poll : cursor -> Callbacks.t -> int option -> int

read_poll cursor callbacks max_option 对 callbacks 上的相应函数调用最多 max_option 个从 cursor 的 runtime_events 读取的事件，并返回读取的事件数。