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_source =
38 | Normal
39 | Marshal
40 | Custom
41 type allocation = private {
46 n_samples : int ; (* The number of samples in this block (>= 1).
47 *)
48 size : int ; (* The size of the block, in words, excluding the
49 header.
50 *)
51 source : allocation_source ; (* The type of the allocation.
52 *)
53 callstack : Printexc.raw_backtrace ; (* The callstack for the alloca‐
54 tion.
55 *)
56 }
57 The type of metadata associated with allocations. This is the type of
60 records passed to the callback triggered by the sampling of an alloca‐
61 tion.
62 type ('minor, 'major) tracker = {
65 alloc_minor : allocation -> 'minor option ;
66 alloc_major : allocation -> 'major option ;
67 promote : 'minor -> 'major option ;
68 dealloc_minor : 'minor -> unit ;
69 dealloc_major : 'major -> unit ;
70 }
71 A ('minor, 'major) tracker describes how memprof should track sampled
74 blocks over their lifetime, keeping a user-defined piece of metadata
75 for each of them: 'minor is the type of metadata to keep for minor
76 blocks, and 'major the type of metadata for major blocks.
77 When using threads, it is guaranteed that allocation callbacks are al‐
79 ways run in the thread where the allocation takes place.
80 If an allocation-tracking or promotion-tracking function returns None ,
82 memprof stops tracking the corresponding value.
83 val null_tracker : ('minor, 'major) tracker
87 Default callbacks simply return None or ()
89 val start : sampling_rate:float -> ?callstack_size:int -> ('minor, 'ma‐
94 jor) tracker -> unit
95 Start the sampling with the given parameters. Fails if sampling is al‐
97 ready active.
98 The parameter sampling_rate is the sampling rate in samples per word
100 (including headers). Usually, with cheap callbacks, a rate of 1e-4 has
101 no visible effect on performance, and 1e-3 causes the program to run a
102 few percent slower
103 The parameter callstack_size is the length of the callstack recorded at
105 every sample. Its default is max_int .
106 The parameter tracker determines how to track sampled blocks over their
108 lifetime in the minor and major heap.
109 Sampling is temporarily disabled when calling a callback for the cur‐
111 rent thread. So they do not need to be re-entrant if the program is
112 single-threaded. However, if threads are used, it is possible that a
113 context switch occurs during a callback, in this case the callback
114 functions must be re-entrant.
115 Note that the callback can be postponed slightly after the actual
117 event. The callstack passed to the callback is always accurate, but the
118 program state may have evolved.
119 val stop : unit -> unit
123 Stop the sampling. Fails if sampling is not active.
125 This function does not allocate memory.
127 All the already tracked blocks are discarded. If there are pending
129 postponed callbacks, they may be discarded.
130 Calling stop when a callback is running can lead to callbacks not being
132 called even though some events happened.
133OCamldoc 2022-07-22 Gc.Memprof(3)