This repository has been archived on 2022-04-04. You can view files and clone it, but cannot push or open issues or pull requests.

391 lines
25 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="Source of the Rust file `&#x2F;home&#x2F;runner&#x2F;.cargo&#x2F;registry&#x2F;src&#x2F;github.com-1ecc6299db9ec823&#x2F;crossbeam-channel-0.5.4&#x2F;src&#x2F;context.rs`."><meta name="keywords" content="rust, rustlang, rust-lang"><title>context.rs - source</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" type="text/css" href="../../normalize.css"><link rel="stylesheet" type="text/css" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../ayu.css" disabled><link rel="stylesheet" type="text/css" href="../../dark.css" disabled><link rel="stylesheet" type="text/css" href="../../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../../storage.js"></script><script src="../../crates.js"></script><script defer src="../../main.js"></script><script defer src="../../source-script.js"></script><script defer src="../../source-files.js"></script>
<noscript><link rel="stylesheet" href="../../noscript.css"></noscript><link rel="alternate icon" type="image/png" href="../../favicon-16x16.png"><link rel="alternate icon" type="image/png" href="../../favicon-32x32.png"><link rel="icon" type="image/svg+xml" href="../../favicon.svg"></head><body class="rustdoc source"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu" role="button">&#9776;</div><a class="sidebar-logo" href="../../crossbeam_channel/index.html"><div class="logo-container"><img class="rust-logo" src="../../rust-logo.png" alt="logo"></div>
</a></nav><main><div class="width-limiter"><div class="sub-container"><a class="sub-logo-container" href="../../crossbeam_channel/index.html"><img class="rust-logo" src="../../rust-logo.png" alt="logo"></a><nav class="sub"><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu" title="themes"><img width="18" height="18" alt="Pick another theme!" src="../../brush.svg"></button><div id="theme-choices" role="menu"></div></div><form class="search-form"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press S to search, ? for more options…" type="search"></div><button type="button" id="help-button" title="help">?</button><a id="settings-menu" href="../../settings.html" title="settings"><img width="18" height="18" alt="Change settings" src="../../wheel.svg"></a></div></form></nav></div><section id="main-content" class="content"><div class="example-wrap"><pre class="line-numbers"><span id="1"> 1</span>
<span id="2"> 2</span>
<span id="3"> 3</span>
<span id="4"> 4</span>
<span id="5"> 5</span>
<span id="6"> 6</span>
<span id="7"> 7</span>
<span id="8"> 8</span>
<span id="9"> 9</span>
<span id="10"> 10</span>
<span id="11"> 11</span>
<span id="12"> 12</span>
<span id="13"> 13</span>
<span id="14"> 14</span>
<span id="15"> 15</span>
<span id="16"> 16</span>
<span id="17"> 17</span>
<span id="18"> 18</span>
<span id="19"> 19</span>
<span id="20"> 20</span>
<span id="21"> 21</span>
<span id="22"> 22</span>
<span id="23"> 23</span>
<span id="24"> 24</span>
<span id="25"> 25</span>
<span id="26"> 26</span>
<span id="27"> 27</span>
<span id="28"> 28</span>
<span id="29"> 29</span>
<span id="30"> 30</span>
<span id="31"> 31</span>
<span id="32"> 32</span>
<span id="33"> 33</span>
<span id="34"> 34</span>
<span id="35"> 35</span>
<span id="36"> 36</span>
<span id="37"> 37</span>
<span id="38"> 38</span>
<span id="39"> 39</span>
<span id="40"> 40</span>
<span id="41"> 41</span>
<span id="42"> 42</span>
<span id="43"> 43</span>
<span id="44"> 44</span>
<span id="45"> 45</span>
<span id="46"> 46</span>
<span id="47"> 47</span>
<span id="48"> 48</span>
<span id="49"> 49</span>
<span id="50"> 50</span>
<span id="51"> 51</span>
<span id="52"> 52</span>
<span id="53"> 53</span>
<span id="54"> 54</span>
<span id="55"> 55</span>
<span id="56"> 56</span>
<span id="57"> 57</span>
<span id="58"> 58</span>
<span id="59"> 59</span>
<span id="60"> 60</span>
<span id="61"> 61</span>
<span id="62"> 62</span>
<span id="63"> 63</span>
<span id="64"> 64</span>
<span id="65"> 65</span>
<span id="66"> 66</span>
<span id="67"> 67</span>
<span id="68"> 68</span>
<span id="69"> 69</span>
<span id="70"> 70</span>
<span id="71"> 71</span>
<span id="72"> 72</span>
<span id="73"> 73</span>
<span id="74"> 74</span>
<span id="75"> 75</span>
<span id="76"> 76</span>
<span id="77"> 77</span>
<span id="78"> 78</span>
<span id="79"> 79</span>
<span id="80"> 80</span>
<span id="81"> 81</span>
<span id="82"> 82</span>
<span id="83"> 83</span>
<span id="84"> 84</span>
<span id="85"> 85</span>
<span id="86"> 86</span>
<span id="87"> 87</span>
<span id="88"> 88</span>
<span id="89"> 89</span>
<span id="90"> 90</span>
<span id="91"> 91</span>
<span id="92"> 92</span>
<span id="93"> 93</span>
<span id="94"> 94</span>
<span id="95"> 95</span>
<span id="96"> 96</span>
<span id="97"> 97</span>
<span id="98"> 98</span>
<span id="99"> 99</span>
<span id="100">100</span>
<span id="101">101</span>
<span id="102">102</span>
<span id="103">103</span>
<span id="104">104</span>
<span id="105">105</span>
<span id="106">106</span>
<span id="107">107</span>
<span id="108">108</span>
<span id="109">109</span>
<span id="110">110</span>
<span id="111">111</span>
<span id="112">112</span>
<span id="113">113</span>
<span id="114">114</span>
<span id="115">115</span>
<span id="116">116</span>
<span id="117">117</span>
<span id="118">118</span>
<span id="119">119</span>
<span id="120">120</span>
<span id="121">121</span>
<span id="122">122</span>
<span id="123">123</span>
<span id="124">124</span>
<span id="125">125</span>
<span id="126">126</span>
<span id="127">127</span>
<span id="128">128</span>
<span id="129">129</span>
<span id="130">130</span>
<span id="131">131</span>
<span id="132">132</span>
<span id="133">133</span>
<span id="134">134</span>
<span id="135">135</span>
<span id="136">136</span>
<span id="137">137</span>
<span id="138">138</span>
<span id="139">139</span>
<span id="140">140</span>
<span id="141">141</span>
<span id="142">142</span>
<span id="143">143</span>
<span id="144">144</span>
<span id="145">145</span>
<span id="146">146</span>
<span id="147">147</span>
<span id="148">148</span>
<span id="149">149</span>
<span id="150">150</span>
<span id="151">151</span>
<span id="152">152</span>
<span id="153">153</span>
<span id="154">154</span>
<span id="155">155</span>
<span id="156">156</span>
<span id="157">157</span>
<span id="158">158</span>
<span id="159">159</span>
<span id="160">160</span>
<span id="161">161</span>
<span id="162">162</span>
<span id="163">163</span>
<span id="164">164</span>
<span id="165">165</span>
<span id="166">166</span>
<span id="167">167</span>
<span id="168">168</span>
<span id="169">169</span>
<span id="170">170</span>
<span id="171">171</span>
<span id="172">172</span>
<span id="173">173</span>
<span id="174">174</span>
<span id="175">175</span>
<span id="176">176</span>
<span id="177">177</span>
<span id="178">178</span>
<span id="179">179</span>
<span id="180">180</span>
<span id="181">181</span>
<span id="182">182</span>
<span id="183">183</span>
<span id="184">184</span>
<span id="185">185</span>
<span id="186">186</span>
<span id="187">187</span>
<span id="188">188</span>
<span id="189">189</span>
<span id="190">190</span>
<span id="191">191</span>
<span id="192">192</span>
<span id="193">193</span>
</pre><pre class="rust"><code><span class="doccomment">//! Thread-local context used in select.</span>
<span class="kw">use</span> <span class="ident">std::cell::Cell</span>;
<span class="kw">use</span> <span class="ident">std::ptr</span>;
<span class="kw">use</span> <span class="ident">std::sync::atomic</span>::{<span class="ident">AtomicPtr</span>, <span class="ident">AtomicUsize</span>, <span class="ident">Ordering</span>};
<span class="kw">use</span> <span class="ident">std::sync::Arc</span>;
<span class="kw">use</span> <span class="ident">std::thread</span>::{<span class="self">self</span>, <span class="ident">Thread</span>, <span class="ident">ThreadId</span>};
<span class="kw">use</span> <span class="ident">std::time::Instant</span>;
<span class="kw">use</span> <span class="ident">crossbeam_utils::Backoff</span>;
<span class="kw">use</span> <span class="ident"><span class="kw">crate</span>::select::Selected</span>;
<span class="doccomment">/// Thread-local context used in select.</span>
<span class="comment">// This is a private API that is used by the select macro.</span>
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>, <span class="ident">Clone</span>)]</span>
<span class="kw">pub</span> <span class="kw">struct</span> <span class="ident">Context</span> {
<span class="ident">inner</span>: <span class="ident">Arc</span><span class="op">&lt;</span><span class="ident">Inner</span><span class="op">&gt;</span>,
}
<span class="doccomment">/// Inner representation of `Context`.</span>
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">struct</span> <span class="ident">Inner</span> {
<span class="doccomment">/// Selected operation.</span>
<span class="ident">select</span>: <span class="ident">AtomicUsize</span>,
<span class="doccomment">/// A slot into which another thread may store a pointer to its `Packet`.</span>
<span class="ident">packet</span>: <span class="ident">AtomicPtr</span><span class="op">&lt;</span>()<span class="op">&gt;</span>,
<span class="doccomment">/// Thread handle.</span>
<span class="ident">thread</span>: <span class="ident">Thread</span>,
<span class="doccomment">/// Thread id.</span>
<span class="ident">thread_id</span>: <span class="ident">ThreadId</span>,
}
<span class="kw">impl</span> <span class="ident">Context</span> {
<span class="doccomment">/// Creates a new context for the duration of the closure.</span>
<span class="attribute">#[<span class="ident">inline</span>]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">with</span><span class="op">&lt;</span><span class="ident">F</span>, <span class="ident">R</span><span class="op">&gt;</span>(<span class="ident">f</span>: <span class="ident">F</span>) -&gt; <span class="ident">R</span>
<span class="kw">where</span>
<span class="ident">F</span>: <span class="ident">FnOnce</span>(<span class="kw-2">&amp;</span><span class="ident">Context</span>) -&gt; <span class="ident">R</span>,
{
<span class="macro">thread_local!</span> {
<span class="doccomment">/// Cached thread-local context.</span>
<span class="kw">static</span> <span class="ident">CONTEXT</span>: <span class="ident">Cell</span><span class="op">&lt;</span><span class="prelude-ty">Option</span><span class="op">&lt;</span><span class="ident">Context</span><span class="op">&gt;</span><span class="op">&gt;</span> <span class="op">=</span> <span class="ident">Cell::new</span>(<span class="prelude-val">Some</span>(<span class="ident">Context::new</span>()));
}
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">f</span> <span class="op">=</span> <span class="prelude-val">Some</span>(<span class="ident">f</span>);
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">f</span> <span class="op">=</span> <span class="op">|</span><span class="ident">cx</span>: <span class="kw-2">&amp;</span><span class="ident">Context</span><span class="op">|</span> -&gt; <span class="ident">R</span> {
<span class="kw">let</span> <span class="ident">f</span> <span class="op">=</span> <span class="ident">f</span>.<span class="ident">take</span>().<span class="ident">unwrap</span>();
<span class="ident">f</span>(<span class="ident">cx</span>)
};
<span class="ident">CONTEXT</span>
.<span class="ident">try_with</span>(<span class="op">|</span><span class="ident">cell</span><span class="op">|</span> <span class="kw">match</span> <span class="ident">cell</span>.<span class="ident">take</span>() {
<span class="prelude-val">None</span> =&gt; <span class="ident">f</span>(<span class="kw-2">&amp;</span><span class="ident">Context::new</span>()),
<span class="prelude-val">Some</span>(<span class="ident">cx</span>) =&gt; {
<span class="ident">cx</span>.<span class="ident">reset</span>();
<span class="kw">let</span> <span class="ident">res</span> <span class="op">=</span> <span class="ident">f</span>(<span class="kw-2">&amp;</span><span class="ident">cx</span>);
<span class="ident">cell</span>.<span class="ident">set</span>(<span class="prelude-val">Some</span>(<span class="ident">cx</span>));
<span class="ident">res</span>
}
})
.<span class="ident">unwrap_or_else</span>(<span class="op">|</span><span class="kw">_</span><span class="op">|</span> <span class="ident">f</span>(<span class="kw-2">&amp;</span><span class="ident">Context::new</span>()))
}
<span class="doccomment">/// Creates a new `Context`.</span>
<span class="attribute">#[<span class="ident">cold</span>]</span>
<span class="kw">fn</span> <span class="ident">new</span>() -&gt; <span class="ident">Context</span> {
<span class="ident">Context</span> {
<span class="ident">inner</span>: <span class="ident">Arc::new</span>(<span class="ident">Inner</span> {
<span class="ident">select</span>: <span class="ident">AtomicUsize::new</span>(<span class="ident">Selected::Waiting</span>.<span class="ident">into</span>()),
<span class="ident">packet</span>: <span class="ident">AtomicPtr::new</span>(<span class="ident">ptr::null_mut</span>()),
<span class="ident">thread</span>: <span class="ident">thread::current</span>(),
<span class="ident">thread_id</span>: <span class="ident">thread::current</span>().<span class="ident">id</span>(),
}),
}
}
<span class="doccomment">/// Resets `select` and `packet`.</span>
<span class="attribute">#[<span class="ident">inline</span>]</span>
<span class="kw">fn</span> <span class="ident">reset</span>(<span class="kw-2">&amp;</span><span class="self">self</span>) {
<span class="self">self</span>.<span class="ident">inner</span>
.<span class="ident">select</span>
.<span class="ident">store</span>(<span class="ident">Selected::Waiting</span>.<span class="ident">into</span>(), <span class="ident">Ordering::Release</span>);
<span class="self">self</span>.<span class="ident">inner</span>.<span class="ident">packet</span>.<span class="ident">store</span>(<span class="ident">ptr::null_mut</span>(), <span class="ident">Ordering::Release</span>);
}
<span class="doccomment">/// Attempts to select an operation.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// On failure, the previously selected operation is returned.</span>
<span class="attribute">#[<span class="ident">inline</span>]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">try_select</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">select</span>: <span class="ident">Selected</span>) -&gt; <span class="prelude-ty">Result</span><span class="op">&lt;</span>(), <span class="ident">Selected</span><span class="op">&gt;</span> {
<span class="self">self</span>.<span class="ident">inner</span>
.<span class="ident">select</span>
.<span class="ident">compare_exchange</span>(
<span class="ident">Selected::Waiting</span>.<span class="ident">into</span>(),
<span class="ident">select</span>.<span class="ident">into</span>(),
<span class="ident">Ordering::AcqRel</span>,
<span class="ident">Ordering::Acquire</span>,
)
.<span class="ident">map</span>(<span class="op">|</span><span class="kw">_</span><span class="op">|</span> ())
.<span class="ident">map_err</span>(<span class="op">|</span><span class="ident">e</span><span class="op">|</span> <span class="ident">e</span>.<span class="ident">into</span>())
}
<span class="doccomment">/// Returns the selected operation.</span>
<span class="attribute">#[<span class="ident">inline</span>]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">selected</span>(<span class="kw-2">&amp;</span><span class="self">self</span>) -&gt; <span class="ident">Selected</span> {
<span class="ident">Selected::from</span>(<span class="self">self</span>.<span class="ident">inner</span>.<span class="ident">select</span>.<span class="ident">load</span>(<span class="ident">Ordering::Acquire</span>))
}
<span class="doccomment">/// Stores a packet.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This method must be called after `try_select` succeeds and there is a packet to provide.</span>
<span class="attribute">#[<span class="ident">inline</span>]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">store_packet</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">packet</span>: <span class="kw-2">*mut</span> ()) {
<span class="kw">if</span> <span class="op">!</span><span class="ident">packet</span>.<span class="ident">is_null</span>() {
<span class="self">self</span>.<span class="ident">inner</span>.<span class="ident">packet</span>.<span class="ident">store</span>(<span class="ident">packet</span>, <span class="ident">Ordering::Release</span>);
}
}
<span class="doccomment">/// Waits until a packet is provided and returns it.</span>
<span class="attribute">#[<span class="ident">inline</span>]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">wait_packet</span>(<span class="kw-2">&amp;</span><span class="self">self</span>) -&gt; <span class="kw-2">*mut</span> () {
<span class="kw">let</span> <span class="ident">backoff</span> <span class="op">=</span> <span class="ident">Backoff::new</span>();
<span class="kw">loop</span> {
<span class="kw">let</span> <span class="ident">packet</span> <span class="op">=</span> <span class="self">self</span>.<span class="ident">inner</span>.<span class="ident">packet</span>.<span class="ident">load</span>(<span class="ident">Ordering::Acquire</span>);
<span class="kw">if</span> <span class="op">!</span><span class="ident">packet</span>.<span class="ident">is_null</span>() {
<span class="kw">return</span> <span class="ident">packet</span>;
}
<span class="ident">backoff</span>.<span class="ident">snooze</span>();
}
}
<span class="doccomment">/// Waits until an operation is selected and returns it.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// If the deadline is reached, `Selected::Aborted` will be selected.</span>
<span class="attribute">#[<span class="ident">inline</span>]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">wait_until</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">deadline</span>: <span class="prelude-ty">Option</span><span class="op">&lt;</span><span class="ident">Instant</span><span class="op">&gt;</span>) -&gt; <span class="ident">Selected</span> {
<span class="comment">// Spin for a short time, waiting until an operation is selected.</span>
<span class="kw">let</span> <span class="ident">backoff</span> <span class="op">=</span> <span class="ident">Backoff::new</span>();
<span class="kw">loop</span> {
<span class="kw">let</span> <span class="ident">sel</span> <span class="op">=</span> <span class="ident">Selected::from</span>(<span class="self">self</span>.<span class="ident">inner</span>.<span class="ident">select</span>.<span class="ident">load</span>(<span class="ident">Ordering::Acquire</span>));
<span class="kw">if</span> <span class="ident">sel</span> <span class="op">!</span><span class="op">=</span> <span class="ident">Selected::Waiting</span> {
<span class="kw">return</span> <span class="ident">sel</span>;
}
<span class="kw">if</span> <span class="ident">backoff</span>.<span class="ident">is_completed</span>() {
<span class="kw">break</span>;
} <span class="kw">else</span> {
<span class="ident">backoff</span>.<span class="ident">snooze</span>();
}
}
<span class="kw">loop</span> {
<span class="comment">// Check whether an operation has been selected.</span>
<span class="kw">let</span> <span class="ident">sel</span> <span class="op">=</span> <span class="ident">Selected::from</span>(<span class="self">self</span>.<span class="ident">inner</span>.<span class="ident">select</span>.<span class="ident">load</span>(<span class="ident">Ordering::Acquire</span>));
<span class="kw">if</span> <span class="ident">sel</span> <span class="op">!</span><span class="op">=</span> <span class="ident">Selected::Waiting</span> {
<span class="kw">return</span> <span class="ident">sel</span>;
}
<span class="comment">// If there&#39;s a deadline, park the current thread until the deadline is reached.</span>
<span class="kw">if</span> <span class="kw">let</span> <span class="prelude-val">Some</span>(<span class="ident">end</span>) <span class="op">=</span> <span class="ident">deadline</span> {
<span class="kw">let</span> <span class="ident">now</span> <span class="op">=</span> <span class="ident">Instant::now</span>();
<span class="kw">if</span> <span class="ident">now</span> <span class="op">&lt;</span> <span class="ident">end</span> {
<span class="ident">thread::park_timeout</span>(<span class="ident">end</span> <span class="op">-</span> <span class="ident">now</span>);
} <span class="kw">else</span> {
<span class="comment">// The deadline has been reached. Try aborting select.</span>
<span class="kw">return</span> <span class="kw">match</span> <span class="self">self</span>.<span class="ident">try_select</span>(<span class="ident">Selected::Aborted</span>) {
<span class="prelude-val">Ok</span>(()) =&gt; <span class="ident">Selected::Aborted</span>,
<span class="prelude-val">Err</span>(<span class="ident">s</span>) =&gt; <span class="ident">s</span>,
};
}
} <span class="kw">else</span> {
<span class="ident">thread::park</span>();
}
}
}
<span class="doccomment">/// Unparks the thread this context belongs to.</span>
<span class="attribute">#[<span class="ident">inline</span>]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">unpark</span>(<span class="kw-2">&amp;</span><span class="self">self</span>) {
<span class="self">self</span>.<span class="ident">inner</span>.<span class="ident">thread</span>.<span class="ident">unpark</span>();
}
<span class="doccomment">/// Returns the id of the thread this context belongs to.</span>
<span class="attribute">#[<span class="ident">inline</span>]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">thread_id</span>(<span class="kw-2">&amp;</span><span class="self">self</span>) -&gt; <span class="ident">ThreadId</span> {
<span class="self">self</span>.<span class="ident">inner</span>.<span class="ident">thread_id</span>
}
}
</code></pre></div>
</section><section id="search" class="content hidden"></section></div></main><div id="rustdoc-vars" data-root-path="../../" data-current-crate="crossbeam_channel" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.59.0 (9d1b2106e 2022-02-23)" ></div>
</body></html>