Модуль Gc.Memprof

module Memprof: sig .. end

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

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

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

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

type t

тип профиля

type allocation_source =

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

val string_of_allocation_source : allocation_source -> string

type allocation = private {

`n_samples : int;`	`(*`	Количество выборок для этого блока (>= 1).	`*)`
`size : int;`	`(*`	Размер блока в словах, без заголовка.	`*)`
`source : allocation_source;`	`(*`	Причина выделения.	`*)`
`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 программа работает на несколько процентов медленнее. 0.0 <= sampling_rate <= 1.0.

Параметр callstack_size задаёт длину стека вызовов, записываемого при каждой выборке. По умолчанию используется max_int.

Параметр tracker определяет, как отслеживать выбранные блоки на протяжении всего срока их существования в малой и большой кучах.

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

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

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

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

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

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

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

val is_sampling : unit -> bool

Возвращает, выполняется ли выборка для какого-либо профиля в текущем домене. Возвращает None, если в текущем домене выборка не выполняется.

Начиная с 5.5

val stop : unit -> unit

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

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

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

val discard : t -> unit

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