模組 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`	`(*`	網域主要堆積池中的總字數。這是每個池中未配置和使用中的字數總和。 Since 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_POOL_LIVE_WORDS`	`(*`	網域主要堆積池中目前使用中的字數。 Since 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_LARGE_WORDS`	`(*`	網域主要堆積大型配置的總字數。大型配置是指大於最大池大小的配置。 Since 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_POOL_FRAG_WORDS`	`(*`	網域主要堆積池中因碎片而損失的字數。這是因為沒有與配置大小完全相同的池，而需要使用較大尺寸的池。 Since 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_POOL_LIVE_BLOCKS`	`(*`	網域主要堆積池中使用中的區塊。 Since 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_LARGE_BLOCKS`	`(*`	網域主要堆積大型配置中使用中的區塊。 Since 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 上的對應函式呼叫，最多可讀取 cursor 的 runtime_events 中的 max_option 個事件，並傳回讀取的事件數。