Gc.Memprof(3o) OCaml library Gc.Memprof(3o)
NAME
Gc.Memprof - Memprof is a sampling engine for allocated memory words.
Module
Module Gc.Memprof
Documentation
Module Memprof
: sig end
Memprof is a sampling engine for allocated memory words. Every allo-
cated word has a probability of being sampled equal to a configurable
sampling rate. Once a block is sampled, it becomes tracked. A tracked
block triggers a user-defined callback as soon as it is allocated, pro-
moted or deallocated.
Since blocks are composed of several words, a block can potentially be
sampled several times. If a block is sampled several times, then each
of the callback is called once for each event of this block: the multi-
plicity is given in the n_samples field of the allocation structure.
This engine makes it possible to implement a low-overhead memory pro-
filer as an OCaml library.
Note: this API is EXPERIMENTAL. It may change without prior notice.
type allocation_source =
| Normal
| Marshal
| Custom
type allocation = private {
n_samples : int ; (* The number of samples in this block (>= 1).
*)
size : int ; (* The size of the block, in words, excluding the
header.
*)
source : allocation_source ; (* The type of the allocation.
*)
callstack : Printexc.raw_backtrace ; (* The callstack for the alloca-
tion.
*)
}
The type of metadata associated with allocations. This is the type of
records passed to the callback triggered by the sampling of an alloca-
tion.
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 ;
}
A ('minor, 'major) tracker describes how memprof should track sampled
blocks over their lifetime, keeping a user-defined piece of metadata
for each of them: 'minor is the type of metadata to keep for minor
blocks, and 'major the type of metadata for major blocks.
When using threads, it is guaranteed that allocation callbacks are al-
ways run in the thread where the allocation takes place.
If an allocation-tracking or promotion-tracking function returns None ,
memprof stops tracking the corresponding value.
val null_tracker : ('minor, 'major) tracker
Default callbacks simply return None or ()
val start : sampling_rate:float -> ?callstack_size:int -> ('minor, 'ma-
jor) tracker -> unit
Start the sampling with the given parameters. Fails if sampling is al-
ready active.
The parameter sampling_rate is the sampling rate in samples per word
(including headers). Usually, with cheap callbacks, a rate of 1e-4 has
no visible effect on performance, and 1e-3 causes the program to run a
few percent slower
The parameter callstack_size is the length of the callstack recorded at
every sample. Its default is max_int .
The parameter tracker determines how to track sampled blocks over their
lifetime in the minor and major heap.
Sampling is temporarily disabled when calling a callback for the cur-
rent thread. So they do not need to be re-entrant if the program is
single-threaded. However, if threads are used, it is possible that a
context switch occurs during a callback, in this case the callback
functions must be re-entrant.
Note that the callback can be postponed slightly after the actual
event. The callstack passed to the callback is always accurate, but the
program state may have evolved.
val stop : unit -> unit
Stop the sampling. Fails if sampling is not active.
This function does not allocate memory.
All the already tracked blocks are discarded. If there are pending
postponed callbacks, they may be discarded.
Calling stop when a callback is running can lead to callbacks not being
called even though some events happened.
OCamldoc 2023-02-12 Gc.Memprof(3o)
Generated by dwww version 1.15 on Sun Jun 23 04:10:38 CEST 2024.