module Memprof:sig
..end
Memprof
is a sampling engine for allocated memory words. Every
allocated 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, promoted 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 multiplicity is given in the n_samples
field of the
allocation
structure.
This engine makes it possible to implement a low-overhead memory profiler 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 : |
(* | The number of samples in this block (>= 1). | *) |
|
size : |
(* | The size of the block, in words, excluding the header. | *) |
|
source : |
(* | The type of the allocation. | *) |
|
callstack : |
(* | The callstack for the allocation. | *) |
}
The type of metadata associated with allocations. This is the type of records passed to the callback triggered by the sampling of an allocation.
type ('minor, 'major)
tracker = {
|
alloc_minor : |
|
alloc_major : |
|
promote : |
|
dealloc_minor : |
|
dealloc_major : |
}
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 always 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, 'major) tracker -> unit
Start the sampling with the given parameters. Fails if sampling is already 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 current 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.