mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-17 08:06:43 -05:00
6 lines
No EOL
9.3 KiB
HTML
6 lines
No EOL
9.3 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Memprof (ocaml.Stdlib.Gc.Memprof)</title><link rel="stylesheet" href="../../../../_odoc-theme/odoc.css"/><meta charset="utf-8"/><meta name="generator" content="odoc 2.2.1"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../../../index.html">ocaml</a> » <a href="../../index.html">Stdlib</a> » <a href="../index.html">Gc</a> » Memprof</nav><header class="odoc-preamble"><h1>Module <code><span>Gc.Memprof</span></code></h1><p><code>Memprof</code> 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.</p><p>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 <code>n_samples</code> field of the <code>allocation</code> structure.</p><p>This engine makes it possible to implement a low-overhead memory profiler as an OCaml library.</p><p>Note: this API is EXPERIMENTAL. It may change without prior notice.</p></header><div class="odoc-content"><div class="odoc-spec"><div class="spec type anchored" id="type-allocation_source"><a href="#type-allocation_source" class="anchor"></a><code><span><span class="keyword">type</span> allocation_source</span><span> = </span></code><ol><li id="type-allocation_source.Normal" class="def variant constructor anchored"><a href="#type-allocation_source.Normal" class="anchor"></a><code><span>| </span><span><span class="constructor">Normal</span></span></code></li><li id="type-allocation_source.Marshal" class="def variant constructor anchored"><a href="#type-allocation_source.Marshal" class="anchor"></a><code><span>| </span><span><span class="constructor">Marshal</span></span></code></li><li id="type-allocation_source.Custom" class="def variant constructor anchored"><a href="#type-allocation_source.Custom" class="anchor"></a><code><span>| </span><span><span class="constructor">Custom</span></span></code></li></ol></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-allocation"><a href="#type-allocation" class="anchor"></a><code><span><span class="keyword">type</span> allocation</span><span> = <span class="keyword">private</span> </span><span>{</span></code><ol><li id="type-allocation.n_samples" class="def record field anchored"><a href="#type-allocation.n_samples" class="anchor"></a><code><span>n_samples : int;</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>The number of samples in this block (>= 1).</p><span class="comment-delim">*)</span></div></li><li id="type-allocation.size" class="def record field anchored"><a href="#type-allocation.size" class="anchor"></a><code><span>size : int;</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>The size of the block, in words, excluding the header.</p><span class="comment-delim">*)</span></div></li><li id="type-allocation.source" class="def record field anchored"><a href="#type-allocation.source" class="anchor"></a><code><span>source : <a href="#type-allocation_source">allocation_source</a>;</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>The type of the allocation.</p><span class="comment-delim">*)</span></div></li><li id="type-allocation.callstack" class="def record field anchored"><a href="#type-allocation.callstack" class="anchor"></a><code><span>callstack : <a href="../../Printexc/index.html#type-raw_backtrace">Printexc.raw_backtrace</a>;</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>The callstack for the allocation.</p><span class="comment-delim">*)</span></div></li></ol><code><span>}</span></code></div><div class="spec-doc"><p>The type of metadata associated with allocations. This is the type of records passed to the callback triggered by the sampling of an allocation.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-tracker"><a href="#type-tracker" class="anchor"></a><code><span><span class="keyword">type</span> <span>('minor, 'major) tracker</span></span><span> = </span><span>{</span></code><ol><li id="type-tracker.alloc_minor" class="def record field anchored"><a href="#type-tracker.alloc_minor" class="anchor"></a><code><span>alloc_minor : <span><a href="#type-allocation">allocation</a> <span class="arrow">-></span></span> <span><span class="type-var">'minor</span> option</span>;</span></code></li><li id="type-tracker.alloc_major" class="def record field anchored"><a href="#type-tracker.alloc_major" class="anchor"></a><code><span>alloc_major : <span><a href="#type-allocation">allocation</a> <span class="arrow">-></span></span> <span><span class="type-var">'major</span> option</span>;</span></code></li><li id="type-tracker.promote" class="def record field anchored"><a href="#type-tracker.promote" class="anchor"></a><code><span>promote : <span><span class="type-var">'minor</span> <span class="arrow">-></span></span> <span><span class="type-var">'major</span> option</span>;</span></code></li><li id="type-tracker.dealloc_minor" class="def record field anchored"><a href="#type-tracker.dealloc_minor" class="anchor"></a><code><span>dealloc_minor : <span><span class="type-var">'minor</span> <span class="arrow">-></span></span> unit;</span></code></li><li id="type-tracker.dealloc_major" class="def record field anchored"><a href="#type-tracker.dealloc_major" class="anchor"></a><code><span>dealloc_major : <span><span class="type-var">'major</span> <span class="arrow">-></span></span> unit;</span></code></li></ol><code><span>}</span></code></div><div class="spec-doc"><p>A <code>('minor, 'major) tracker</code> describes how memprof should track sampled blocks over their lifetime, keeping a user-defined piece of metadata for each of them: <code>'minor</code> is the type of metadata to keep for minor blocks, and <code>'major</code> the type of metadata for major blocks.</p><p>When using threads, it is guaranteed that allocation callbacks are always run in the thread where the allocation takes place.</p><p>If an allocation-tracking or promotion-tracking function returns <code>None</code>, memprof stops tracking the corresponding value.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-null_tracker"><a href="#val-null_tracker" class="anchor"></a><code><span><span class="keyword">val</span> null_tracker : <span><span>(<span class="type-var">'minor</span>, <span class="type-var">'major</span>)</span> <a href="#type-tracker">tracker</a></span></span></code></div><div class="spec-doc"><p>Default callbacks simply return <code>None</code> or <code>()</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-start"><a href="#val-start" class="anchor"></a><code><span><span class="keyword">val</span> start :
|
||
<span>sampling_rate:float <span class="arrow">-></span></span>
|
||
<span>?callstack_size:int <span class="arrow">-></span></span>
|
||
<span><span><span>(<span class="type-var">'minor</span>, <span class="type-var">'major</span>)</span> <a href="#type-tracker">tracker</a></span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p>Start the sampling with the given parameters. Fails if sampling is already active.</p><p>The parameter <code>sampling_rate</code> 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</p><p>The parameter <code>callstack_size</code> is the length of the callstack recorded at every sample. Its default is <code>max_int</code>.</p><p>The parameter <code>tracker</code> determines how to track sampled blocks over their lifetime in the minor and major heap.</p><p>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.</p><p>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.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-stop"><a href="#val-stop" class="anchor"></a><code><span><span class="keyword">val</span> stop : <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Stop the sampling. Fails if sampling is not active.</p><p>This function does not allocate memory.</p><p>All the already tracked blocks are discarded. If there are pending postponed callbacks, they may be discarded.</p><p>Calling <code>stop</code> when a callback is running can lead to callbacks not being called even though some events happened.</p></div></div></div></body></html> |