1Gc.Memprof(3) OCaml library Gc.Memprof(3)
2
6 Gc.Memprof - Memprof is a sampling engine for allocated memory words.
7
9 Module Gc.Memprof
10
12 Module Memprof
13 : sig end
14 Memprof is a sampling engine for allocated memory words. Every allo‐
18 cated word has a probability of being sampled equal to a configurable
19 sampling rate. Once a block is sampled, it becomes tracked. A tracked
20 block triggers a user-defined callback as soon as it is allocated, pro‐
21 moted or deallocated.
22 Since blocks are composed of several words, a block can potentially be
24 sampled several times. If a block is sampled several times, then each
25 of the callback is called once for each event of this block: the multi‐
26 plicity is given in the n_samples field of the allocation structure.
27 This engine makes it possible to implement a low-overhead memory pro‐
29 filer as an OCaml library.
30 Note: this API is EXPERIMENTAL. It may change without prior notice.
32 type allocation = private {
38 n_samples : int ; (* The number of samples in this block (>= 1).
39 *)
40 size : int ; (* The size of the block, in words, excluding the
41 header.
42 *)
43 unmarshalled : bool ; (* Whether the block comes from unmarshalling.
44 *)
45 callstack : Printexc.raw_backtrace ; (* The callstack for the alloca‐
46 tion.
47 *)
48 }
49 The type of metadata associated with allocations. This is the type of
52 records passed to the callback triggered by the sampling of an alloca‐
53 tion.
54 type ('minor, 'major) tracker = {
57 alloc_minor : allocation -> 'minor option ;
58 alloc_major : allocation -> 'major option ;
59 promote : 'minor -> 'major option ;
60 dealloc_minor : 'minor -> unit ;
61 dealloc_major : 'major -> unit ;
62 }
63 A ('minor, 'major) tracker describes how memprof should track sampled
66 blocks over their lifetime, keeping a user-defined piece of metadata
67 for each of them: 'minor is the type of metadata to keep for minor
68 blocks, and 'major the type of metadata for major blocks.
69 If an allocation-tracking or promotion-tracking function returns None ,
71 memprof stops tracking the corresponding value.
72 val null_tracker : ('minor, 'major) tracker
76 Default callbacks simply return None or ()
78 val start : sampling_rate:float -> ?callstack_size:int -> ('minor,
83 'major) tracker -> unit
84 Start the sampling with the given parameters. Fails if sampling is
86 already active.
87 The parameter sampling_rate is the sampling rate in samples per word
89 (including headers). Usually, with cheap callbacks, a rate of 1e-4 has
90 no visible effect on performance, and 1e-3 causes the program to run a
91 few percent slower
92 The parameter callstack_size is the length of the callstack recorded at
94 every sample. Its default is max_int .
95 The parameter tracker determines how to track sampled blocks over their
97 lifetime in the minor and major heap.
98 Sampling is temporarily disabled when calling a callback for the cur‐
100 rent thread. So they do not need to be reentrant if the program is sin‐
101 gle-threaded. However, if threads are used, it is possible that a con‐
102 text switch occurs during a callback, in this case the callback func‐
103 tions must be reentrant.
104 Note that the callback can be postponed slightly after the actual
106 event. The callstack passed to the callback is always accurate, but the
107 program state may have evolved.
108 Calling Thread.exit in a callback is currently unsafe and can result in
110 undefined behavior.
111 val stop : unit -> unit
115 Stop the sampling. Fails if sampling is not active.
117 This function does not allocate memory, but tries to run the postponed
119 callbacks for already allocated memory blocks (of course, these call‐
120 backs may allocate).
121 All the already tracked blocks are discarded.
123 Calling stop when a callback is running can lead to callbacks not being
125 called even though some events happened.
126OCamldoc 2020-09-01 Gc.Memprof(3)