Модуль Gc.Memprof

module Memprof: sig .. end

Memprof — это движок профилирования, который случайным образом отбирает выделенные слова памяти. Каждое выделенное слово имеет вероятность быть выбранным, равную настраиваемой частоте выборки. После выбора блока он отслеживается. Отслеживаемый блок вызывает пользовательский обратный вызов, как только он выделяется, продвигает или освобождается.

Поскольку блоки состоят из нескольких слов, блок может потенциально быть выбран несколько раз. Если блок выбирается несколько раз, каждый из обратных вызовов вызывается один раз для каждого события этого блока: кратность указана в поле n_samples структуры allocation.

Этот движок позволяет реализовать профилировщик памяти с низким уровнем накладных расходов как библиотеку OCaml.

Примечание: этот API является ЭКСПЕРИМЕНТАЛЬНЫМ. Он может измениться без предварительного уведомления.

type t

тип профиля

type allocation_source =

`\|`	`Normal`
`\|`	`Marshal`
`\|`	`Custom`

type allocation = private {

`n_samples : int;`	`(*`	Количество выборок в этом блоке (>= 1).	`*)`
`size : int;`	`(*`	Размер блока в словах, за исключением заголовка.	`*)`
`source : allocation_source;`	`(*`	Причина выделения; `Marshal` не может быть создано с OCaml 5.	`*)`
`callstack : Printexc.raw_backtrace;`	`(*`	Стек вызовов для выделения.	`*)`

}

Тип метаданных, связанных с выделениями. Это тип записей, передаваемых в обратный вызов, вызванный выборкой выделения.

type ('minor, 'major) tracker = {

	`alloc_minor : allocation -> 'minor option;`
	`alloc_major : allocation -> 'major option;`
	`promote : 'minor -> 'major option;`
	`dealloc_minor : 'minor -> unit;`
	`dealloc_major : 'major -> unit;`

}

('minor, 'major) tracker описывает, как memprof должен отслеживать выбранные блоки на протяжении их жизненного цикла, сохраняя пользовательские данные о каждом из них: 'minor — это тип метаданных для сохранения для малых блоков, а 'major — для больших блоков.

Члены функции tracker являются обратными вызовами.

Если обратный вызов выделения или продвижения вызывает исключение или возвращает None, memprof прекращает отслеживание соответствующего блока.

val null_tracker : ('minor, 'major) tracker

Обратные вызовы по умолчанию просто возвращают None или ()

val start : sampling_rate:float ->       ?callstack_size:int -> ('minor, 'major) tracker -> t

Запускает профиль с заданными параметрами. Вызывает исключение, если профиль уже выполняет выборку в текущем домене.

Выборки начинаются немедленно. Параметр sampling_rate — это частота выборки в выборках на слово (включая заголовки). Обычно с дешевыми обратными вызовами частота 1e-4 не оказывает заметного влияния на производительность, а 1e-3 замедляет выполнение программы на несколько процентов.

Параметр callstack_size — это длина стека вызовов, записываемого при каждом выборе. Его значение по умолчанию — max_int.

Параметр tracker определяет, как отслеживать выбранные блоки на протяжении их жизненного цикла в куче minor и major.

Выборки временно отключаются в текущем потоке при вызове обратного вызова, поэтому обратные вызовы не обязательно должны быть повторно-входными, если программа однопоточная и однодоменная. Однако, если используются потоки или несколько доменов, возможно, что несколько обратных вызовов будут выполняться параллельно. В этом случае функции обратного вызова должны быть повторно-входными.

Обратите внимание, что обратный вызов может быть отложен на короткое время после фактического события. Стек вызовов, передаваемый обратному вызову выделения, всегда точно отражает выделение, но состояние программы может измениться между выделением и вызовом обратного вызова.

Если новый поток или домен создаются во время профилирования, дочерний поток или домен присоединяются к этому профилю (используя те же обратные вызовы sampling_rate, callstack_size и tracker).

Обратный вызов выделения обычно выполняется потоком, который выделил блок. Если поток завершается или профиль останавливается до вызова обратного вызова, обратный вызов может быть выполнен другим потоком.

Каждый обратный вызов, как правило, выполняется доменом, который выделил блок. Если домен завершается или профиль останавливается до вызова обратного вызова, обратный вызов может быть выполнен другим доменом.

Разные домены могут одновременно выполнять разные профили.

val stop : unit -> unit

Останавливает выборку для текущего профиля. Не удается, если в текущем домене не выполняется выборка ни одного профиля. Останавливает выборку во всех потоках и доменах, совместно использующих профиль.

Обратные вызовы из профиля могут выполняться после вызова stop, пока не будет применено discard к профилю.

Профиль неявно останавливается (но не отбрасывается), если все домены и потоки, выполняющие выборки для него, завершаются.

val discard : t -> unit

Отбрасывает все состояние профилирования для остановленного профиля, что предотвращает дальнейшие обратные вызовы для него. Вызывает исключение, если вызывается для профиля, который не был остановлен.