Модуль 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`

Тип событий span, генерируемых во время выполнения.

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 событий, прочитанных из runtime_events cursor, и возвращает количество прочитанных событий.