1Gc.Memprof(3)                    OCaml library                   Gc.Memprof(3)
2
3
4

NAME

6       Gc.Memprof - Memprof is a sampling engine for allocated memory words.
7

Module

9       Module   Gc.Memprof
10

Documentation

12       Module Memprof
13        : sig end
14
15
16
17       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
23       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
28       This engine makes it possible to implement a low-overhead  memory  pro‐
29       filer as an OCaml library.
30
31       Note: this API is EXPERIMENTAL. It may change without prior notice.
32
33
34
35
36
37       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
50
51       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
55
56       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
64
65       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
70       If an allocation-tracking or promotion-tracking function returns None ,
71       memprof stops tracking the corresponding value.
72
73
74
75       val null_tracker : ('minor, 'major) tracker
76
77       Default callbacks simply return None or ()
78
79
80
81
82       val start : sampling_rate:float -> ?callstack_size:int -> ('minor, 'ma‐
83       jor) tracker -> unit
84
85       Start the sampling with the given parameters. Fails if sampling is  al‐
86       ready active.
87
88       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
93       The parameter callstack_size is the length of the callstack recorded at
94       every sample. Its default is max_int .
95
96       The parameter tracker determines how to track sampled blocks over their
97       lifetime in the minor and major heap.
98
99       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
105       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
109       Calling Thread.exit in a callback is currently unsafe and can result in
110       undefined behavior.
111
112
113
114       val stop : unit -> unit
115
116       Stop the sampling. Fails if sampling is not active.
117
118       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
122       All the already tracked blocks are discarded.
123
124       Calling stop when a callback is running can lead to callbacks not being
125       called even though some events happened.
126
127
128
129
130
131OCamldoc                          2021-01-26                     Gc.Memprof(3)
Impressum