Модуль Runtime_events

module Runtime_events: sig .. end

События времени выполнения — трассировка времени выполнения на основе кольцевого буфера

Этот модуль позволяет пользователям включать и подписываться на события трассировки от сборщика мусора и других частей среды выполнения OCaml. Это может быть полезно для диагностики или мониторинга производительности. Этот модуль может использоваться для подписки на события для текущего процесса или внешних процессов асинхронно.

Когда включен (либо с помощью установки переменной среды OCAML_RUNTIME_EVENTS_START, либо вызова Runtime_events.start), будет создан файл с идентификатором процесса и расширением .events. По умолчанию он находится в текущем каталоге, но может быть переопределен переменной среды OCAML_RUNTIME_EVENTS_DIR. Каждый домен поддерживает свой собственный кольцевой буфер в разделе большего файла, в который он отправляет события.

Существует также набор C API в runtime_events.h, который может обеспечить мониторинг текущего процесса без влияния или привязки для других языков.

Поведение системы событий времени выполнения можно контролировать с помощью следующих переменных среды:

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`

Тип для событий счетчика, генерируемых средой выполнения

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`

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

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