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.