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 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 : 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 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 : 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 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.

OCamldoc                                           2022-01-24                                     Gc.Memprof(3o)