Module Memprof_limits.MemprofSource

This is a reimplementation of Gc.Memprof on top of Memprof-limits, with the same interface. (Its signature is included in particular in module type of Stdlib__Gc.Memprof.)

Generally, one must not use Memprof-limits and Gc.Memprof on the same domain. Instead, you can use the present module if you need to profile a domain that simultaneously uses Memprof-limits. It is also possible to use Gc.Memprof and Memprof-limits simultaneously inside distinct domain hierarchies.

This module is experimental. In addition, from OCaml 5.3 to OCaml < 5.5, this module was not fully implemented; it only worked in simple-enough situations.

Note: the expectancy (1/sampling_rate) provided in Memprof.start is rounded to the nearest integer for the accuracy of allocation limits accounting. The sampling rate must also not be lower than the default sampling rate of Memprof-limits.

Sourcetype t

the type of a profile

Sourcetype allocation_source = Gc.Memprof.allocation_source =
  1. | Normal
  2. | Marshal
  3. | Custom
Sourcetype allocation = Gc.Memprof.allocation = {
  1. n_samples : int;
    (*

    The number of samples in this block (>= 1).

    *)
  2. size : int;
    (*

    The size of the block, in words, excluding the header.

    *)
  3. source : allocation_source;
    (*

    The cause of the allocation.

    *)
  4. 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.

Sourcetype ('minor, 'major) tracker = ('minor, 'major) Gc.Memprof.tracker = {
  1. alloc_minor : allocation -> 'minor option;
  2. alloc_major : allocation -> 'major option;
  3. promote : 'minor -> 'major option;
  4. dealloc_minor : 'minor -> unit;
  5. 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.

The member functions in a tracker are called callbacks.

If an allocation or promotion callback raises an exception or returns None, memprof stops tracking the corresponding block.

Sourceval null_tracker : ('minor, 'major) tracker

Default callbacks simply return None or ()

Sourceval start : sampling_rate:float -> ?callstack_size:int -> ('minor, 'major) tracker -> t

Start a profile with the given parameters. Raises an exception if a profile is already sampling in the current domain.

Sampling begins immediately. 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. 0.0 <= sampling_rate <= 1.0.

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 and running callbacks are temporarily disabled on the current thread when calling a callback, so callbacks do not need to be re-entrant if the program is single-threaded and single-domain. However, if threads or multiple domains are used, it is possible that several callbacks will run in parallel. In this case, callback functions must be re-entrant.

Note that a callback may be postponed slightly after the actual event. The callstack passed to an allocation callback always accurately reflects the allocation, but the program state may have evolved between the allocation and the call to the callback.

If a new thread or domain is created when the current domain is sampling for a profile, the child thread or domain joins that profile (using the same sampling_rate, callstack_size, and tracker callbacks).

An allocation callback is always run by the thread which allocated the block. If the thread exits or the profile is stopped before the callback is called, the allocation callback is not called and the block is not tracked.

Each subsequent callback is generally run by the domain which allocated the block. If the domain terminates or the profile is stopped before the callback is called, the callback may be run by a different domain.

Different domains may sample for different profiles simultaneously.

Sourceval stop : unit -> unit

Stop sampling for the current profile. Fails if no profile is sampling in the current domain. Stops sampling in all threads and domains sharing the profile.

Promotion and deallocation callbacks from a profile may run after stop is called, until discard is applied to the profile.

A profile is implicitly stopped (but not discarded) if all domains and threads sampling for it are terminated.

Sourceval discard : t -> unit

Discards all profiling state for a stopped profile, which prevents any more callbacks for it. Raises an exception if called on a profile which has not been stopped.