mirror of
https://github.com/ocaml-tracing/ocaml-trace.git
synced 2026-03-08 03:47:57 -04:00
2 lines
8.2 KiB
HTML
2 lines
8.2 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Mtime_clock (mtime.Mtime_clock)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.1.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">mtime</a> » Mtime_clock</nav><header class="odoc-preamble"><h1>Module <code><span>Mtime_clock</span></code></h1><p>Monotonic time clock.</p><p><code>Mtime_clock</code> provides access to a system monotonic clock. This time increases monotonically and is not subject to operating system calendar time adjustments.</p><p>Only use <a href="#val-now"><code>Mtime_clock.now</code></a> if you need inter-process time correlation, otherwise prefer <a href="#val-elapsed"><code>Mtime_clock.elapsed</code></a> and <a href="#counters" title="counters">counters</a>.</p><p>Consult important information about <a href="#err" title="err">error handling</a> and <a href="#platform_support" title="platform_support">platform support</a>.</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#clock">Monotonic clock</a></li><li><a href="#counters">Time counters</a></li><li><a href="#raw">Monotonic clock raw interface</a></li><li><a href="#err">Error handling</a></li><li><a href="#platform_support">Platform support</a></li></ul></nav></div><div class="odoc-content"><h2 id="clock"><a href="#clock" class="anchor"></a>Monotonic clock</h2><div class="odoc-spec"><div class="spec value anchored" id="val-elapsed"><a href="#val-elapsed" class="anchor"></a><code><span><span class="keyword">val</span> elapsed : <span>unit <span class="arrow">-></span></span> <a href="../Mtime/index.html#type-span">Mtime.span</a></span></code></div><div class="spec-doc"><p><code>elapsed ()</code> is the monotonic time span elapsed since the beginning of the program.</p><p>Raises <code>Sys_error</code>, see <a href="#err" title="err">error handling</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-now"><a href="#val-now" class="anchor"></a><code><span><span class="keyword">val</span> now : <span>unit <span class="arrow">-></span></span> <a href="../Mtime/index.html#type-t">Mtime.t</a></span></code></div><div class="spec-doc"><p><code>now ()</code> is the current system-relative monotonic timestamp. Its absolute value is meaningless.</p><p>Raises <code>Sys_error</code>, see <a href="#err" title="err">error handling</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-period"><a href="#val-period" class="anchor"></a><code><span><span class="keyword">val</span> period : <span>unit <span class="arrow">-></span></span> <span><a href="../Mtime/index.html#type-span">Mtime.span</a> option</span></span></code></div><div class="spec-doc"><p><code>period ()</code> is the clock's period as a monotonic time span (if available).</p></div></div><h2 id="counters"><a href="#counters" class="anchor"></a>Time counters</h2><div class="odoc-spec"><div class="spec type anchored" id="type-counter"><a href="#type-counter" class="anchor"></a><code><span><span class="keyword">type</span> counter</span></code></div><div class="spec-doc"><p>The type for monotonic wall-clock time counters.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-counter"><a href="#val-counter" class="anchor"></a><code><span><span class="keyword">val</span> counter : <span>unit <span class="arrow">-></span></span> <a href="#type-counter">counter</a></span></code></div><div class="spec-doc"><p><code>counter ()</code> is a counter counting from now on.</p><p>Raises <code>Sys_error</code>, see <a href="#err" title="err">error handling</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-count"><a href="#val-count" class="anchor"></a><code><span><span class="keyword">val</span> count : <span><a href="#type-counter">counter</a> <span class="arrow">-></span></span> <a href="../Mtime/index.html#type-span">Mtime.span</a></span></code></div><div class="spec-doc"><p><code>count c</code> is the monotonic time span elapsed since <code>c</code> was created.</p></div></div><h2 id="raw"><a href="#raw" class="anchor"></a>Monotonic clock raw interface</h2><div class="odoc-spec"><div class="spec value anchored" id="val-elapsed_ns"><a href="#val-elapsed_ns" class="anchor"></a><code><span><span class="keyword">val</span> elapsed_ns : <span>unit <span class="arrow">-></span></span> int64</span></code></div><div class="spec-doc"><p><code>elapsed_ns ()</code> is the <em>unsigned</em> 64-bit integer nanosecond monotonic time span elapsed since the beginning of the program.</p><p>Raises <code>Sys_error</code>, see <a href="#err" title="err">error handling</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-now_ns"><a href="#val-now_ns" class="anchor"></a><code><span><span class="keyword">val</span> now_ns : <span>unit <span class="arrow">-></span></span> int64</span></code></div><div class="spec-doc"><p><code>now_ns ()</code> is an <em>unsigned</em> 64-bit integer nanosecond system-relative monotonic timestamp. The absolute value is meaningless.</p><p>Raises <code>Sys_error</code>, see <a href="#err" title="err">error handling</a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-period_ns"><a href="#val-period_ns" class="anchor"></a><code><span><span class="keyword">val</span> period_ns : <span>unit <span class="arrow">-></span></span> <span>int64 option</span></span></code></div><div class="spec-doc"><p><code>period_ns ()</code> is the clock's period as an <em>unsigned</em> 64-bit integer nanosecond monotonic time span (if available).</p></div></div><h2 id="err"><a href="#err" class="anchor"></a>Error handling</h2><p>The functions <a href="#val-elapsed"><code>elapsed</code></a>, <a href="#val-now"><code>now</code></a>, <a href="#val-counter"><code>counter</code></a>, <a href="#val-elapsed_ns"><code>elapsed_ns</code></a> and <a href="#val-now_ns"><code>now_ns</code></a> raise <code>Sys_error</code> whenever they can't determine the current time or that it doesn't fit in <code>Mtime</code>'s range. Usually this exception should only be catched at the toplevel of your program to log it and abort the program. It indicates a serious error condition in the system.</p><p>All the other functions, whose functionality is less essential, simply silently return <code>None</code> if they can't determine the information either because it is unavailable or because an error occured.</p><h2 id="platform_support"><a href="#platform_support" class="anchor"></a>Platform support</h2><ul><li>Linux uses <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_gettime.html"><code>clock_gettime</code></a> with <a href="https://www.man7.org/linux/man-pages/man3/clock_settime.3.html">CLOCK_BOOTTIME</a>. This means that sleep time is taken into account.</li><li>Platforms with a POSIX clock use <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_gettime.html"><code>clock_gettime</code></a> with CLOCK_MONOTONIC.</li><li>Darwin uses <a href="https://developer.apple.com/documentation/kernel/1646199-mach_continuous_time"><code>mach_continous_time</code></a>. This means that sleep time is taken into account.</li><li>Windows uses <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa373083%28v=vs.85%29.aspx">Performance counters</a>.</li><li>JavaScript uses <a href="http://www.w3.org/TR/hr-time/"><code>performance.now</code></a> (consult <a href="http://caniuse.com/#feat=high-resolution-time">availability</a>) which returns a <a href="http://www.w3.org/TR/hr-time/#sec-DOMHighResTimeStamp">double floating point value</a> in milliseconds with resolution up to the microsecond.</li><li>JavaScript running on Node.js uses the built-in <a href="https://nodejs.org/api/perf_hooks.html#perf_hooks_performance_now"><code>perf_hooks</code></a> module, which provides an interface compatible to the <code>performance</code> module in browsers.</li></ul></div></body></html>
|