edlang/tracing/instrument/trait.WithSubscriber.html
2024-04-13 08:42:00 +00:00

61 lines
14 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="Extension trait allowing futures to be instrumented with a `tracing` `Subscriber`."><title>WithSubscriber in tracing::instrument - 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-5bc39a1768837dd0.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.77.2 (25ef9e3d8 2024-04-09)" data-channel="1.77.2" data-search-js="search-dd67cee4cfa65049.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../../static.files/storage-4c98445ec4002617.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../static.files/main-48f368f3872407c8.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-04d5337699b92874.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 trait"><!--[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" title="show sidebar"></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="#">WithSubscriber</a></h2><div class="sidebar-elems"><section><h3><a href="#provided-methods">Provided Methods</a></h3><ul class="block"><li><a href="#method.with_current_subscriber">with_current_subscriber</a></li><li><a href="#method.with_subscriber">with_subscriber</a></li></ul><h3><a href="#object-safety">Object Safety</a></h3><h3><a href="#implementors">Implementors</a></h3></section><h2><a href="index.html">In tracing::instrument</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>Trait <a href="../index.html">tracing</a>::<wbr><a href="index.html">instrument</a>::<wbr><a class="trait" href="#">WithSubscriber</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/instrument.rs.html#136-234">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><pre class="rust item-decl"><code>pub trait WithSubscriber: <a class="trait" href="https://doc.rust-lang.org/1.77.2/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a> {
// Provided methods
fn <a href="#method.with_subscriber" class="fn">with_subscriber</a>&lt;S&gt;(self, subscriber: S) -&gt; <a class="struct" href="struct.WithDispatch.html" title="struct tracing::instrument::WithDispatch">WithDispatch</a>&lt;Self&gt; <a href="#" class="tooltip" data-notable-ty="WithDispatch&lt;Self&gt;"></a>
<span class="where">where S: <a class="trait" href="https://doc.rust-lang.org/1.77.2/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="struct" href="../struct.Dispatch.html" title="struct tracing::Dispatch">Dispatch</a>&gt;</span> { ... }
<span class="item-spacer"></span> fn <a href="#method.with_current_subscriber" class="fn">with_current_subscriber</a>(self) -&gt; <a class="struct" href="struct.WithDispatch.html" title="struct tracing::instrument::WithDispatch">WithDispatch</a>&lt;Self&gt; <a href="#" class="tooltip" data-notable-ty="WithDispatch&lt;Self&gt;"></a> { ... }
}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Extension trait allowing futures to be instrumented with
a <code>tracing</code> <a href="../trait.Subscriber.html" title="trait tracing::Subscriber"><code>Subscriber</code></a>.</p>
</div></details><h2 id="provided-methods" class="section-header">Provided Methods<a href="#provided-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="method.with_subscriber" class="method"><a class="src rightside" href="../../src/tracing/instrument.rs.html#176-184">source</a><h4 class="code-header">fn <a href="#method.with_subscriber" class="fn">with_subscriber</a>&lt;S&gt;(self, subscriber: S) -&gt; <a class="struct" href="struct.WithDispatch.html" title="struct tracing::instrument::WithDispatch">WithDispatch</a>&lt;Self&gt; <a href="#" class="tooltip" data-notable-ty="WithDispatch&lt;Self&gt;"></a><div class="where">where
S: <a class="trait" href="https://doc.rust-lang.org/1.77.2/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="struct" href="../struct.Dispatch.html" title="struct tracing::Dispatch">Dispatch</a>&gt;,</div></h4></section></summary><div class="docblock"><p>Attaches the provided <a href="../trait.Subscriber.html" title="trait tracing::Subscriber"><code>Subscriber</code></a> to this type, returning a
<a href="struct.WithDispatch.html" title="struct tracing::instrument::WithDispatch"><code>WithDispatch</code></a> wrapper.</p>
<p>The attached <a href="../trait.Subscriber.html" title="trait tracing::Subscriber"><code>Subscriber</code></a> will be set as the <a href="../dispatcher/index.html#setting-the-default-subscriber" title="mod tracing::dispatcher">default</a> when the returned
<a href="https://doc.rust-lang.org/1.77.2/core/future/future/trait.Future.html" title="trait core::future::future::Future"><code>Future</code></a> is polled.</p>
<h5 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tracing::instrument::WithSubscriber;
<span class="comment">// Set the default `Subscriber`
</span><span class="kw">let </span>_default = tracing::subscriber::set_default(MySubscriber::default());
<span class="macro">tracing::info!</span>(<span class="string">"this event will be recorded by the default `Subscriber`"</span>);
<span class="comment">// Create a different `Subscriber` and attach it to a future.
</span><span class="kw">let </span>other_subscriber = MyOtherSubscriber::default();
<span class="kw">let </span>future = <span class="kw">async </span>{
<span class="macro">tracing::info!</span>(<span class="string">"this event will be recorded by the other `Subscriber`"</span>);
<span class="comment">// ...
</span>};
future
<span class="comment">// Attach the other `Subscriber` to the future before awaiting it
</span>.with_subscriber(other_subscriber)
.<span class="kw">await</span>;
<span class="comment">// Once the future has completed, we return to the default `Subscriber`.
</span><span class="macro">tracing::info!</span>(<span class="string">"this event will be recorded by the default `Subscriber`"</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.with_current_subscriber" class="method"><a class="src rightside" href="../../src/tracing/instrument.rs.html#228-233">source</a><h4 class="code-header">fn <a href="#method.with_current_subscriber" class="fn">with_current_subscriber</a>(self) -&gt; <a class="struct" href="struct.WithDispatch.html" title="struct tracing::instrument::WithDispatch">WithDispatch</a>&lt;Self&gt; <a href="#" class="tooltip" data-notable-ty="WithDispatch&lt;Self&gt;"></a></h4></section></summary><div class="docblock"><p>Attaches the current <a href="../dispatcher/index.html#setting-the-default-subscriber" title="mod tracing::dispatcher">default</a> <a href="../trait.Subscriber.html" title="trait tracing::Subscriber"><code>Subscriber</code></a> to this type, returning a
<a href="struct.WithDispatch.html" title="struct tracing::instrument::WithDispatch"><code>WithDispatch</code></a> wrapper.</p>
<p>The attached <code>Subscriber</code> will be set as the <a href="../dispatcher/index.html#setting-the-default-subscriber" title="mod tracing::dispatcher">default</a> when the returned
<a href="https://doc.rust-lang.org/1.77.2/core/future/future/trait.Future.html" title="trait core::future::future::Future"><code>Future</code></a> is polled.</p>
<p>This can be used to propagate the current dispatcher context when
spawning a new future that may run on a different thread.</p>
<h5 id="examples-1"><a class="doc-anchor" href="#examples-1">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tracing::instrument::WithSubscriber;
<span class="comment">// Using `set_default` (rather than `set_global_default`) sets the
// default `Subscriber` for *this* thread only.
</span><span class="kw">let </span>_default = tracing::subscriber::set_default(MySubscriber::default());
<span class="kw">let </span>future = <span class="kw">async </span>{
<span class="comment">// ...
</span>};
<span class="comment">// If a multi-threaded async runtime is in use, this spawned task may
// run on a different thread, in a different default `Subscriber`'s context.
</span>tokio::spawn(future);
<span class="comment">// However, calling `with_current_subscriber` on the future before
// spawning it, ensures that the current thread's default `Subscriber` is
// propagated to the spawned task, regardless of where it executes:
</span>tokio::spawn(future.with_current_subscriber());</code></pre></div>
</div></details></div><h2 id="object-safety" class="section-header">Object Safety<a href="#object-safety" class="anchor">§</a></h2><div class="object-safety-info">This trait is <b>not</b> <a href="https://doc.rust-lang.org/1.77.2/reference/items/traits.html#object-safety">object safe</a>.</div><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"><section id="impl-WithSubscriber-for-T" class="impl"><a class="src rightside" href="../../src/tracing/instrument.rs.html#393">source</a><a href="#impl-WithSubscriber-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T: <a class="trait" href="https://doc.rust-lang.org/1.77.2/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>&gt; <a class="trait" href="trait.WithSubscriber.html" title="trait tracing::instrument::WithSubscriber">WithSubscriber</a> for T</h3></section></div><script src="../../trait.impl/tracing/instrument/trait.WithSubscriber.js" async></script><script type="text/json" id="notable-traits-data">{"WithDispatch<Self>":"<h3>Notable traits for <code><a class=\"struct\" href=\"struct.WithDispatch.html\" title=\"struct tracing::instrument::WithDispatch\">WithDispatch</a>&lt;T&gt;</code></h3><pre><code><div class=\"where\">impl&lt;T: <a class=\"trait\" href=\"https://doc.rust-lang.org/1.77.2/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a>&gt; <a class=\"trait\" href=\"https://doc.rust-lang.org/1.77.2/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a> for <a class=\"struct\" href=\"struct.WithDispatch.html\" title=\"struct tracing::instrument::WithDispatch\">WithDispatch</a>&lt;T&gt;</div><div class=\"where\"> type <a href=\"https://doc.rust-lang.org/1.77.2/core/future/future/trait.Future.html#associatedtype.Output\" class=\"associatedtype\">Output</a> = T::<a class=\"associatedtype\" href=\"https://doc.rust-lang.org/1.77.2/core/future/future/trait.Future.html#associatedtype.Output\" title=\"type core::future::future::Future::Output\">Output</a>;</div>"}</script></section></div></main></body></html>