edg-l/edlang
1
1
Fork 0
mirror of https://github.com/edg-l/edlang.git synced 2024-09-20 01:24:23 +00:00
Code Issues Packages Projects Releases Wiki Activity
edlang/tracing/dispatcher/index.html
edg-l 5c4cbb28c1 deploy: 4a83cfd6f9
2024-02-13 06:38:44 +00:00

67 lines
11 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Dispatches trace events to `Subscriber`s."><title>tracing::dispatcher - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><link rel="stylesheet" href="../../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../../static.files/rustdoc-ac92e1bbe349e143.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="tracing" data-themes="" data-resource-suffix="" data-rustdoc-version="1.76.0 (07dca489a 2024-02-04)" data-channel="1.76.0" data-search-js="search-2b6ce74ff89ae146.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../../static.files/storage-f2adc0d6ca4d09fb.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../static.files/main-305769736d49e732.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-feafe1bb7466e4bd.css"></noscript><link rel="alternate icon" type="image/png" href="../../static.files/favicon-16x16-8b506e7a72182f1c.png"><link rel="alternate icon" type="image/png" href="../../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc mod"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">&#9776;</button><a class="logo-container" href="../../tracing/index.html"><img src="https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png" alt=""></a></nav><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="../../tracing/index.html"><img src="https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png" alt="logo"></a><h2><a href="../../tracing/index.html">tracing</a><span class="version">0.1.40</span></h2></div><h2 class="location"><a href="#">Module dispatcher</a></h2><div class="sidebar-elems"><section><ul class="block"><li><a href="#structs">Structs</a></li><li><a href="#functions">Functions</a></li></ul></section><h2><a href="../index.html">In crate tracing</a></h2></div></nav><div class="sidebar-resizer"></div>
<main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><div id="sidebar-button" tabindex="-1"><a href="../../tracing/all.html" title="show sidebar"></a></div><input class="search-input" name="search" aria-label="Run search in the documentation" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" tabindex="-1"><a href="../../help.html" title="help">?</a></div><div id="settings-menu" tabindex="-1"><a href="../../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1>Module <a href="../index.html">tracing</a>::<wbr><a class="mod" href="#">dispatcher</a><button id="copy-path" title="Copy item path to clipboard"><img src="../../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="src" href="../../src/tracing/dispatcher.rs.html#1-145">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Dispatches trace events to <a href="../trait.Subscriber.html" title="trait tracing::Subscriber"><code>Subscriber</code></a>s.</p>
<p>The <em>dispatcher</em> is the component of the tracing system which is responsible
for forwarding trace data from the instrumentation points that generate it
to the subscriber that collects it.</p>
<h2 id="using-the-trace-dispatcher"><a href="#using-the-trace-dispatcher">Using the Trace Dispatcher</a></h2>
<p>Every thread in a program using <code>tracing</code> has a <em>default subscriber</em>. When
events occur, or spans are created, they are dispatched to the thread’s
current subscriber.</p>
<h3 id="setting-the-default-subscriber"><a href="#setting-the-default-subscriber">Setting the Default Subscriber</a></h3>
<p>By default, the current subscriber is an empty implementation that does
nothing. To use a subscriber implementation, it must be set as the default.
There are two methods for doing so: <a href="fn.with_default.html" title="fn tracing::dispatcher::with_default"><code>with_default</code></a> and
<a href="fn.set_global_default.html" title="fn tracing::dispatcher::set_global_default"><code>set_global_default</code></a>. <code>with_default</code> sets the default subscriber for the
duration of a scope, while <code>set_global_default</code> sets a default subscriber
for the entire process.</p>
<p>To use either of these functions, we must first wrap our subscriber in a
<a href="../struct.Dispatch.html" title="struct tracing::Dispatch"><code>Dispatch</code></a>, a cloneable, type-erased reference to a subscriber. For
example:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>dispatcher::Dispatch;
<span class="kw">let </span>my_subscriber = FooSubscriber::new();
<span class="kw">let </span>my_dispatch = Dispatch::new(my_subscriber);</code></pre></div>
<p>Then, we can use <a href="fn.with_default.html" title="fn tracing::dispatcher::with_default"><code>with_default</code></a> to set our <code>Dispatch</code> as the default for
the duration of a block:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="comment">// no default subscriber
</span>dispatcher::with_default(<span class="kw-2">&amp;</span>my_dispatch, || {
<span class="comment">// my_subscriber is the default
</span>});
<span class="comment">// no default subscriber again</span></code></pre></div>
<p>It’s important to note that <code>with_default</code> will not propagate the current
thread’s default subscriber to any threads spawned within the <code>with_default</code>
block. To propagate the default subscriber to new threads, either use
<code>with_default</code> from the new thread, or use <code>set_global_default</code>.</p>
<p>As an alternative to <code>with_default</code>, we can use <a href="fn.set_global_default.html" title="fn tracing::dispatcher::set_global_default"><code>set_global_default</code></a> to
set a <code>Dispatch</code> as the default for all threads, for the lifetime of the
program. For example:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="comment">// no default subscriber
</span>dispatcher::set_global_default(my_dispatch)
<span class="comment">// `set_global_default` will return an error if the global default
// subscriber has already been set.
</span>.expect(<span class="string">"global default was already set!"</span>);
<span class="comment">// `my_subscriber` is now the default</span></code></pre></div>
<pre class="ignore" style="white-space:normal;font:inherit;">
<strong>Note</strong>: The thread-local scoped dispatcher (<code>with_default</code>)
requires the Rust standard library. <code>no_std</code> users should
use <a href="fn.set_global_default.html"><code>set_global_default</code></a>
instead.
</pre>
<h3 id="accessing-the-default-subscriber"><a href="#accessing-the-default-subscriber">Accessing the Default Subscriber</a></h3>
<p>A thread’s current default subscriber can be accessed using the
<a href="fn.get_default.html" title="fn tracing::dispatcher::get_default"><code>get_default</code></a> function, which executes a closure with a reference to the
currently default <code>Dispatch</code>. This is used primarily by <code>tracing</code>
instrumentation.</p>
</div></details><h2 id="structs" class="section-header"><a href="#structs">Structs</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.DefaultGuard.html" title="struct tracing::dispatcher::DefaultGuard">DefaultGuard</a></div><div class="desc docblock-short">A guard that resets the current default dispatcher to the prior
default dispatcher when dropped.</div></li><li><div class="item-name"><a class="struct" href="struct.Dispatch.html" title="struct tracing::dispatcher::Dispatch">Dispatch</a></div><div class="desc docblock-short"><code>Dispatch</code> trace data to a <a href="../trait.Subscriber.html" title="trait tracing::Subscriber"><code>Subscriber</code></a>.</div></li><li><div class="item-name"><a class="struct" href="struct.SetGlobalDefaultError.html" title="struct tracing::dispatcher::SetGlobalDefaultError">SetGlobalDefaultError</a></div><div class="desc docblock-short">Returned if setting the global dispatcher fails.</div></li><li><div class="item-name"><a class="struct" href="struct.WeakDispatch.html" title="struct tracing::dispatcher::WeakDispatch">WeakDispatch</a></div><div class="desc docblock-short"><code>WeakDispatch</code> is a version of <a href="../struct.Dispatch.html" title="struct tracing::Dispatch"><code>Dispatch</code></a> that holds a non-owning reference
to a <a href="../trait.Subscriber.html" title="trait tracing::Subscriber"><code>Subscriber</code></a>.</div></li></ul><h2 id="functions" class="section-header"><a href="#functions">Functions</a></h2><ul class="item-table"><li><div class="item-name"><a class="fn" href="fn.get_default.html" title="fn tracing::dispatcher::get_default">get_default</a></div><div class="desc docblock-short">Executes a closure with a reference to this thread’s current <a href="../struct.Dispatch.html" title="struct tracing::Dispatch">dispatcher</a>.</div></li><li><div class="item-name"><a class="fn" href="fn.set_default.html" title="fn tracing::dispatcher::set_default">set_default</a></div><div class="desc docblock-short">Sets the dispatch as the default dispatch for the duration of the lifetime
of the returned DefaultGuard</div></li><li><div class="item-name"><a class="fn" href="fn.set_global_default.html" title="fn tracing::dispatcher::set_global_default">set_global_default</a></div><div class="desc docblock-short">Sets this dispatch as the global default for the duration of the entire program.
Will be used as a fallback if no thread-local dispatch has been set in a thread
(using <code>with_default</code>.)</div></li><li><div class="item-name"><a class="fn" href="fn.with_default.html" title="fn tracing::dispatcher::with_default">with_default</a></div><div class="desc docblock-short">Sets this dispatch as the default for the duration of a closure.</div></li></ul></section></div></main></body></html>
Reference in a new issue View git blame Copy permalink