mirror of
https://github.com/c-cube/tiny_httpd.git
synced 2026-01-22 17:36:40 -05:00
6 lines
11 KiB
HTML
6 lines
11 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Memprof (ocaml.Stdlib.Gc.Memprof)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.0.0"/><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">Index</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 profiling engine which randomly samples 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 callbacks 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-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span></code></div><div class="spec-doc"><p>the type of a profile</p></div></div><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 cause 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>The member functions in a <code>tracker</code> are called callbacks.</p><p>If an allocation or promotion callback raises an exception or returns <code>None</code>, memprof stops tracking the corresponding block.</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><span class="label">sampling_rate</span>:float <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?callstack_size</span>: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>
|
||
<a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Start a profile with the given parameters. Raises an exception if a profile is already sampling in the current domain.</p><p>Sampling begins immediately. 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. 0.0 <= sampling_rate <= 1.0.</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 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.</p><p>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.</p><p>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 <code>sampling_rate</code>, <code>callstack_size</code>, and <code>tracker</code> callbacks).</p><p>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.</p><p>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.</p><p>Different domains may sample for different profiles simultaneously.</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 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.</p><p>Promotion and deallocation callbacks from a profile may run after <code>stop</code> is called, until <code>discard</code> is applied to the profile.</p><p>A profile is implicitly stopped (but not discarded) if all domains and threads sampling for it are terminated.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-discard"><a href="#val-discard" class="anchor"></a><code><span><span class="keyword">val</span> discard : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>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.</p></div></div></div></body></html>
|