<main><divclass="width-limiter"><navclass="sub"><formclass="search-form"><span></span><divid="sidebar-button"tabindex="-1"><ahref="../../tracing/all.html"title="show sidebar"></a></div><inputclass="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"><divid="help-button"tabindex="-1"><ahref="../../help.html"title="help">?</a></div><divid="settings-menu"tabindex="-1"><ahref="../../settings.html"title="settings"><imgwidth="22"height="22"alt="Change settings"src="../../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><sectionid="main-content"class="content"><divclass="main-heading"><h1>Module <ahref="../index.html">tracing</a>::<wbr><aclass="mod"href="#">dispatcher</a><buttonid="copy-path"title="Copy item path to clipboard"><imgsrc="../../static.files/clipboard-7571035ce49a181d.svg"width="19"height="18"alt="Copy item path"></button></h1><spanclass="out-of-band"><aclass="src"href="../../src/tracing/dispatcher.rs.html#1-145">source</a> · <buttonid="toggle-all-docs"title="collapse all docs">[<span>−</span>]</button></span></div><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p>Dispatches trace events to <ahref="../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
<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: <ahref="fn.with_default.html"title="fn tracing::dispatcher::with_default"><code>with_default</code></a> and
<ahref="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
<ahref="../struct.Dispatch.html"title="struct tracing::Dispatch"><code>Dispatch</code></a>, a cloneable, type-erased reference to a subscriber. For
<p>Then, we can use <ahref="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>
<divclass="example-wrap"><preclass="rust rust-example-rendered"><code><spanclass="comment">// no default subscriber
<spanclass="comment">// my_subscriber is the default
</span>});
<spanclass="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 <ahref="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>
<divclass="example-wrap"><preclass="rust rust-example-rendered"><code><spanclass="comment">// no default subscriber
<p>A thread’s current default subscriber can be accessed using the
<ahref="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>
</div></details><h2id="structs"class="section-header">Structs<ahref="#structs"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="struct"href="struct.DefaultGuard.html"title="struct tracing::dispatcher::DefaultGuard">DefaultGuard</a></div><divclass="desc docblock-short">A guard that resets the current default dispatcher to the prior
default dispatcher when dropped.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Dispatch.html"title="struct tracing::dispatcher::Dispatch">Dispatch</a></div><divclass="desc docblock-short"><code>Dispatch</code> trace data to a <ahref="../trait.Subscriber.html"title="trait tracing::Subscriber"><code>Subscriber</code></a>.</div></li><li><divclass="item-name"><aclass="struct"href="struct.SetGlobalDefaultError.html"title="struct tracing::dispatcher::SetGlobalDefaultError">SetGlobalDefaultError</a></div><divclass="desc docblock-short">Returned if setting the global dispatcher fails.</div></li><li><divclass="item-name"><aclass="struct"href="struct.WeakDispatch.html"title="struct tracing::dispatcher::WeakDispatch">WeakDispatch</a></div><divclass="desc docblock-short"><code>WeakDispatch</code> is a version of <ahref="../struct.Dispatch.html"title="struct tracing::Dispatch"><code>Dispatch</code></a> that holds a non-owning reference
to a <ahref="../trait.Subscriber.html"title="trait tracing::Subscriber"><code>Subscriber</code></a>.</div></li></ul><h2id="functions"class="section-header">Functions<ahref="#functions"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="fn"href="fn.get_default.html"title="fn tracing::dispatcher::get_default">get_default</a></div><divclass="desc docblock-short">Executes a closure with a reference to this thread’s current <ahref="../struct.Dispatch.html"title="struct tracing::Dispatch">dispatcher</a>.</div></li><li><divclass="item-name"><aclass="fn"href="fn.set_default.html"title="fn tracing::dispatcher::set_default">set_default</a></div><divclass="desc docblock-short">Sets the dispatch as the default dispatch for the duration of the lifetime
of the returned DefaultGuard</div></li><li><divclass="item-name"><aclass="fn"href="fn.set_global_default.html"title="fn tracing::dispatcher::set_global_default">set_global_default</a></div><divclass="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><divclass="item-name"><aclass="fn"href="fn.with_default.html"title="fn tracing::dispatcher::with_default">with_default</a></div><divclass="desc docblock-short">Sets this dispatch as the default for the duration of a closure.</div></li></ul></section></div></main></body></html>
