<!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 to the Rust file `src/libcore/pin.rs`."><meta name="keywords" content="rust, rustlang, rust-lang"><title>pin.rs.html -- source</title><link rel="stylesheet" type="text/css" href="../../normalize1.35.0.css"><link rel="stylesheet" type="text/css" href="../../rustdoc1.35.0.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../dark1.35.0.css"><link rel="stylesheet" type="text/css" href="../../light1.35.0.css" id="themeStyle"><script src="../../storage1.35.0.js"></script><noscript><link rel="stylesheet" href="../../noscript1.35.0.css"></noscript><link rel="shortcut icon" href="../../favicon1.35.0.ico"><style type="text/css">#crate-search{background-image:url("../../down-arrow1.35.0.svg");}</style></head><body class="rustdoc source"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">☰</div><a href='../../core/index.html'><img src='../../rust-logo1.35.0.png' alt='logo' width='100'></a></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../../brush1.35.0.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../../theme1.35.0.js"></script><nav class="sub"><form class="search-form js-only"><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><a id="settings-menu" href="../../settings.html"><img src="../../wheel1.35.0.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><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>
<span id="194">194</span>
<span id="195">195</span>
<span id="196">196</span>
<span id="197">197</span>
<span id="198">198</span>
<span id="199">199</span>
<span id="200">200</span>
<span id="201">201</span>
<span id="202">202</span>
<span id="203">203</span>
<span id="204">204</span>
<span id="205">205</span>
<span id="206">206</span>
<span id="207">207</span>
<span id="208">208</span>
<span id="209">209</span>
<span id="210">210</span>
<span id="211">211</span>
<span id="212">212</span>
<span id="213">213</span>
<span id="214">214</span>
<span id="215">215</span>
<span id="216">216</span>
<span id="217">217</span>
<span id="218">218</span>
<span id="219">219</span>
<span id="220">220</span>
<span id="221">221</span>
<span id="222">222</span>
<span id="223">223</span>
<span id="224">224</span>
<span id="225">225</span>
<span id="226">226</span>
<span id="227">227</span>
<span id="228">228</span>
<span id="229">229</span>
<span id="230">230</span>
<span id="231">231</span>
<span id="232">232</span>
<span id="233">233</span>
<span id="234">234</span>
<span id="235">235</span>
<span id="236">236</span>
<span id="237">237</span>
<span id="238">238</span>
<span id="239">239</span>
<span id="240">240</span>
<span id="241">241</span>
<span id="242">242</span>
<span id="243">243</span>
<span id="244">244</span>
<span id="245">245</span>
<span id="246">246</span>
<span id="247">247</span>
<span id="248">248</span>
<span id="249">249</span>
<span id="250">250</span>
<span id="251">251</span>
<span id="252">252</span>
<span id="253">253</span>
<span id="254">254</span>
<span id="255">255</span>
<span id="256">256</span>
<span id="257">257</span>
<span id="258">258</span>
<span id="259">259</span>
<span id="260">260</span>
<span id="261">261</span>
<span id="262">262</span>
<span id="263">263</span>
<span id="264">264</span>
<span id="265">265</span>
<span id="266">266</span>
<span id="267">267</span>
<span id="268">268</span>
<span id="269">269</span>
<span id="270">270</span>
<span id="271">271</span>
<span id="272">272</span>
<span id="273">273</span>
<span id="274">274</span>
<span id="275">275</span>
<span id="276">276</span>
<span id="277">277</span>
<span id="278">278</span>
<span id="279">279</span>
<span id="280">280</span>
<span id="281">281</span>
<span id="282">282</span>
<span id="283">283</span>
<span id="284">284</span>
<span id="285">285</span>
<span id="286">286</span>
<span id="287">287</span>
<span id="288">288</span>
<span id="289">289</span>
<span id="290">290</span>
<span id="291">291</span>
<span id="292">292</span>
<span id="293">293</span>
<span id="294">294</span>
<span id="295">295</span>
<span id="296">296</span>
<span id="297">297</span>
<span id="298">298</span>
<span id="299">299</span>
<span id="300">300</span>
<span id="301">301</span>
<span id="302">302</span>
<span id="303">303</span>
<span id="304">304</span>
<span id="305">305</span>
<span id="306">306</span>
<span id="307">307</span>
<span id="308">308</span>
<span id="309">309</span>
<span id="310">310</span>
<span id="311">311</span>
<span id="312">312</span>
<span id="313">313</span>
<span id="314">314</span>
<span id="315">315</span>
<span id="316">316</span>
<span id="317">317</span>
<span id="318">318</span>
<span id="319">319</span>
<span id="320">320</span>
<span id="321">321</span>
<span id="322">322</span>
<span id="323">323</span>
<span id="324">324</span>
<span id="325">325</span>
<span id="326">326</span>
<span id="327">327</span>
<span id="328">328</span>
<span id="329">329</span>
<span id="330">330</span>
<span id="331">331</span>
<span id="332">332</span>
<span id="333">333</span>
<span id="334">334</span>
<span id="335">335</span>
<span id="336">336</span>
<span id="337">337</span>
<span id="338">338</span>
<span id="339">339</span>
<span id="340">340</span>
<span id="341">341</span>
<span id="342">342</span>
<span id="343">343</span>
<span id="344">344</span>
<span id="345">345</span>
<span id="346">346</span>
<span id="347">347</span>
<span id="348">348</span>
<span id="349">349</span>
<span id="350">350</span>
<span id="351">351</span>
<span id="352">352</span>
<span id="353">353</span>
<span id="354">354</span>
<span id="355">355</span>
<span id="356">356</span>
<span id="357">357</span>
<span id="358">358</span>
<span id="359">359</span>
<span id="360">360</span>
<span id="361">361</span>
<span id="362">362</span>
<span id="363">363</span>
<span id="364">364</span>
<span id="365">365</span>
<span id="366">366</span>
<span id="367">367</span>
<span id="368">368</span>
<span id="369">369</span>
<span id="370">370</span>
<span id="371">371</span>
<span id="372">372</span>
<span id="373">373</span>
<span id="374">374</span>
<span id="375">375</span>
<span id="376">376</span>
<span id="377">377</span>
<span id="378">378</span>
<span id="379">379</span>
<span id="380">380</span>
<span id="381">381</span>
<span id="382">382</span>
<span id="383">383</span>
<span id="384">384</span>
<span id="385">385</span>
<span id="386">386</span>
<span id="387">387</span>
<span id="388">388</span>
<span id="389">389</span>
<span id="390">390</span>
<span id="391">391</span>
<span id="392">392</span>
<span id="393">393</span>
<span id="394">394</span>
<span id="395">395</span>
<span id="396">396</span>
<span id="397">397</span>
<span id="398">398</span>
<span id="399">399</span>
<span id="400">400</span>
<span id="401">401</span>
<span id="402">402</span>
<span id="403">403</span>
<span id="404">404</span>
<span id="405">405</span>
<span id="406">406</span>
<span id="407">407</span>
<span id="408">408</span>
<span id="409">409</span>
<span id="410">410</span>
<span id="411">411</span>
<span id="412">412</span>
<span id="413">413</span>
<span id="414">414</span>
<span id="415">415</span>
<span id="416">416</span>
<span id="417">417</span>
<span id="418">418</span>
<span id="419">419</span>
<span id="420">420</span>
<span id="421">421</span>
<span id="422">422</span>
<span id="423">423</span>
<span id="424">424</span>
<span id="425">425</span>
<span id="426">426</span>
<span id="427">427</span>
<span id="428">428</span>
<span id="429">429</span>
<span id="430">430</span>
<span id="431">431</span>
<span id="432">432</span>
<span id="433">433</span>
<span id="434">434</span>
<span id="435">435</span>
<span id="436">436</span>
<span id="437">437</span>
<span id="438">438</span>
<span id="439">439</span>
<span id="440">440</span>
<span id="441">441</span>
<span id="442">442</span>
<span id="443">443</span>
<span id="444">444</span>
<span id="445">445</span>
<span id="446">446</span>
<span id="447">447</span>
<span id="448">448</span>
<span id="449">449</span>
<span id="450">450</span>
<span id="451">451</span>
<span id="452">452</span>
<span id="453">453</span>
<span id="454">454</span>
<span id="455">455</span>
<span id="456">456</span>
<span id="457">457</span>
<span id="458">458</span>
<span id="459">459</span>
<span id="460">460</span>
<span id="461">461</span>
<span id="462">462</span>
<span id="463">463</span>
<span id="464">464</span>
<span id="465">465</span>
<span id="466">466</span>
<span id="467">467</span>
<span id="468">468</span>
<span id="469">469</span>
<span id="470">470</span>
<span id="471">471</span>
<span id="472">472</span>
<span id="473">473</span>
<span id="474">474</span>
<span id="475">475</span>
<span id="476">476</span>
<span id="477">477</span>
<span id="478">478</span>
<span id="479">479</span>
<span id="480">480</span>
<span id="481">481</span>
<span id="482">482</span>
<span id="483">483</span>
<span id="484">484</span>
<span id="485">485</span>
<span id="486">486</span>
<span id="487">487</span>
<span id="488">488</span>
<span id="489">489</span>
<span id="490">490</span>
<span id="491">491</span>
<span id="492">492</span>
<span id="493">493</span>
<span id="494">494</span>
<span id="495">495</span>
<span id="496">496</span>
<span id="497">497</span>
<span id="498">498</span>
<span id="499">499</span>
<span id="500">500</span>
<span id="501">501</span>
<span id="502">502</span>
<span id="503">503</span>
<span id="504">504</span>
<span id="505">505</span>
<span id="506">506</span>
<span id="507">507</span>
<span id="508">508</span>
<span id="509">509</span>
<span id="510">510</span>
<span id="511">511</span>
<span id="512">512</span>
<span id="513">513</span>
<span id="514">514</span>
<span id="515">515</span>
<span id="516">516</span>
<span id="517">517</span>
<span id="518">518</span>
<span id="519">519</span>
<span id="520">520</span>
<span id="521">521</span>
<span id="522">522</span>
<span id="523">523</span>
<span id="524">524</span>
<span id="525">525</span>
<span id="526">526</span>
<span id="527">527</span>
<span id="528">528</span>
<span id="529">529</span>
<span id="530">530</span>
<span id="531">531</span>
<span id="532">532</span>
<span id="533">533</span>
<span id="534">534</span>
<span id="535">535</span>
<span id="536">536</span>
<span id="537">537</span>
<span id="538">538</span>
<span id="539">539</span>
<span id="540">540</span>
<span id="541">541</span>
<span id="542">542</span>
<span id="543">543</span>
<span id="544">544</span>
<span id="545">545</span>
<span id="546">546</span>
<span id="547">547</span>
<span id="548">548</span>
<span id="549">549</span>
<span id="550">550</span>
<span id="551">551</span>
<span id="552">552</span>
<span id="553">553</span>
<span id="554">554</span>
<span id="555">555</span>
<span id="556">556</span>
<span id="557">557</span>
<span id="558">558</span>
<span id="559">559</span>
<span id="560">560</span>
<span id="561">561</span>
<span id="562">562</span>
<span id="563">563</span>
<span id="564">564</span>
<span id="565">565</span>
<span id="566">566</span>
<span id="567">567</span>
<span id="568">568</span>
<span id="569">569</span>
<span id="570">570</span>
<span id="571">571</span>
<span id="572">572</span>
<span id="573">573</span>
<span id="574">574</span>
<span id="575">575</span>
<span id="576">576</span>
<span id="577">577</span>
<span id="578">578</span>
<span id="579">579</span>
<span id="580">580</span>
<span id="581">581</span>
<span id="582">582</span>
<span id="583">583</span>
<span id="584">584</span>
<span id="585">585</span>
<span id="586">586</span>
<span id="587">587</span>
<span id="588">588</span>
<span id="589">589</span>
<span id="590">590</span>
<span id="591">591</span>
<span id="592">592</span>
<span id="593">593</span>
<span id="594">594</span>
<span id="595">595</span>
<span id="596">596</span>
<span id="597">597</span>
<span id="598">598</span>
<span id="599">599</span>
<span id="600">600</span>
<span id="601">601</span>
<span id="602">602</span>
<span id="603">603</span>
<span id="604">604</span>
<span id="605">605</span>
<span id="606">606</span>
<span id="607">607</span>
<span id="608">608</span>
<span id="609">609</span>
<span id="610">610</span>
<span id="611">611</span>
<span id="612">612</span>
<span id="613">613</span>
<span id="614">614</span>
<span id="615">615</span>
<span id="616">616</span>
<span id="617">617</span>
<span id="618">618</span>
<span id="619">619</span>
<span id="620">620</span>
<span id="621">621</span>
<span id="622">622</span>
<span id="623">623</span>
<span id="624">624</span>
<span id="625">625</span>
<span id="626">626</span>
<span id="627">627</span>
<span id="628">628</span>
<span id="629">629</span>
<span id="630">630</span>
<span id="631">631</span>
<span id="632">632</span>
<span id="633">633</span>
<span id="634">634</span>
<span id="635">635</span>
</pre><div class="example-wrap"><pre class="rust ">
<span class="doccomment">//! Types that pin data to its location in memory.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! It is sometimes useful to have objects that are guaranteed to not move,</span>
<span class="doccomment">//! in the sense that their placement in memory does not change, and can thus be relied upon.</span>
<span class="doccomment">//! A prime example of such a scenario would be building self-referential structs,</span>
<span class="doccomment">//! since moving an object with pointers to itself will invalidate them,</span>
<span class="doccomment">//! which could cause undefined behavior.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! A [`Pin<P>`] ensures that the pointee of any pointer type `P` has a stable location in memory,</span>
<span class="doccomment">//! meaning it cannot be moved elsewhere and its memory cannot be deallocated</span>
<span class="doccomment">//! until it gets dropped. We say that the pointee is "pinned".</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! By default, all types in Rust are movable. Rust allows passing all types by-value,</span>
<span class="doccomment">//! and common smart-pointer types such as `Box<T>` and `&mut T` allow replacing and</span>
<span class="doccomment">//! moving the values they contain: you can move out of a `Box<T>`, or you can use [`mem::swap`].</span>
<span class="doccomment">//! [`Pin<P>`] wraps a pointer type `P`, so `Pin<Box<T>>` functions much like a regular `Box<T>`:</span>
<span class="doccomment">//! when a `Pin<Box<T>>` gets dropped, so do its contents, and the memory gets deallocated.</span>
<span class="doccomment">//! Similarily, `Pin<&mut T>` is a lot like `&mut T`. However, [`Pin<P>`] does not let clients</span>
<span class="doccomment">//! actually obtain a `Box<T>` or `&mut T` to pinned data, which implies that you cannot use</span>
<span class="doccomment">//! operations such as [`mem::swap`]:</span>
<span class="doccomment">//! ```</span>
<span class="doccomment">//! use std::pin::Pin;</span>
<span class="doccomment">//! fn swap_pins<T>(x: Pin<&mut T>, y: Pin<&mut T>) {</span>
<span class="doccomment">//! // `mem::swap` needs `&mut T`, but we cannot get it.</span>
<span class="doccomment">//! // We are stuck, we cannot swap the contents of these references.</span>
<span class="doccomment">//! // We could use `Pin::get_unchecked_mut`, but that is unsafe for a reason:</span>
<span class="doccomment">//! // we are not allowed to use it for moving things out of the `Pin`.</span>
<span class="doccomment">//! }</span>
<span class="doccomment">//! ```</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! It is worth reiterating that [`Pin<P>`] does *not* change the fact that a Rust compiler</span>
<span class="doccomment">//! considers all types movable. [`mem::swap`] remains callable for any `T`. Instead, `Pin<P>`</span>
<span class="doccomment">//! prevents certain *values* (pointed to by pointers wrapped in `Pin<P>`) from being</span>
<span class="doccomment">//! moved by making it impossible to call methods that require `&mut T` on them</span>
<span class="doccomment">//! (like [`mem::swap`]).</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! [`Pin<P>`] can be used to wrap any pointer type `P`, and as such it interacts with</span>
<span class="doccomment">//! [`Deref`] and [`DerefMut`]. A `Pin<P>` where `P: Deref` should be considered</span>
<span class="doccomment">//! as a "`P`-style pointer" to a pinned `P::Target` -- so, a `Pin<Box<T>>` is</span>
<span class="doccomment">//! an owned pointer to a pinned `T`, and a `Pin<Rc<T>>` is a reference-counted</span>
<span class="doccomment">//! pointer to a pinned `T`.</span>
<span class="doccomment">//! For correctness, [`Pin<P>`] relies on the [`Deref`] and [`DerefMut`] implementations</span>
<span class="doccomment">//! to not move out of their `self` parameter, and to only ever return a pointer</span>
<span class="doccomment">//! to pinned data when they are called on a pinned pointer.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! # `Unpin`</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! However, these restrictions are usually not necessary. Many types are always freely</span>
<span class="doccomment">//! movable, even when pinned, because they do not rely on having a stable address.</span>
<span class="doccomment">//! This includes all the basic types (like `bool`, `i32`, references)</span>
<span class="doccomment">//! as well as types consisting solely of these types.</span>
<span class="doccomment">//! Types that do not care about pinning implement the [`Unpin`] auto-trait, which</span>
<span class="doccomment">//! cancels the effect of [`Pin<P>`]. For `T: Unpin`, `Pin<Box<T>>` and `Box<T>` function</span>
<span class="doccomment">//! identically, as do `Pin<&mut T>` and `&mut T`.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! Note that pinning and `Unpin` only affect the pointed-to type `P::Target`, not the pointer</span>
<span class="doccomment">//! type `P` itself that got wrapped in `Pin<P>`. For example, whether or not `Box<T>` is</span>
<span class="doccomment">//! `Unpin` has no effect on the behavior of `Pin<Box<T>>` (here, `T` is the</span>
<span class="doccomment">//! pointed-to type).</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! # Example: self-referential struct</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! ```rust</span>
<span class="doccomment">//! use std::pin::Pin;</span>
<span class="doccomment">//! use std::marker::PhantomPinned;</span>
<span class="doccomment">//! use std::ptr::NonNull;</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! // This is a self-referential struct since the slice field points to the data field.</span>
<span class="doccomment">//! // We cannot inform the compiler about that with a normal reference,</span>
<span class="doccomment">//! // since this pattern cannot be described with the usual borrowing rules.</span>
<span class="doccomment">//! // Instead we use a raw pointer, though one which is known to not be null,</span>
<span class="doccomment">//! // since we know it's pointing at the string.</span>
<span class="doccomment">//! struct Unmovable {</span>
<span class="doccomment">//! data: String,</span>
<span class="doccomment">//! slice: NonNull<String>,</span>
<span class="doccomment">//! _pin: PhantomPinned,</span>
<span class="doccomment">//! }</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! impl Unmovable {</span>
<span class="doccomment">//! // To ensure the data doesn't move when the function returns,</span>
<span class="doccomment">//! // we place it in the heap where it will stay for the lifetime of the object,</span>
<span class="doccomment">//! // and the only way to access it would be through a pointer to it.</span>
<span class="doccomment">//! fn new(data: String) -> Pin<Box<Self>> {</span>
<span class="doccomment">//! let res = Unmovable {</span>
<span class="doccomment">//! data,</span>
<span class="doccomment">//! // we only create the pointer once the data is in place</span>
<span class="doccomment">//! // otherwise it will have already moved before we even started</span>
<span class="doccomment">//! slice: NonNull::dangling(),</span>
<span class="doccomment">//! _pin: PhantomPinned,</span>
<span class="doccomment">//! };</span>
<span class="doccomment">//! let mut boxed = Box::pin(res);</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! let slice = NonNull::from(&boxed.data);</span>
<span class="doccomment">//! // we know this is safe because modifying a field doesn't move the whole struct</span>
<span class="doccomment">//! unsafe {</span>
<span class="doccomment">//! let mut_ref: Pin<&mut Self> = Pin::as_mut(&mut boxed);</span>
<span class="doccomment">//! Pin::get_unchecked_mut(mut_ref).slice = slice;</span>
<span class="doccomment">//! }</span>
<span class="doccomment">//! boxed</span>
<span class="doccomment">//! }</span>
<span class="doccomment">//! }</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! let unmoved = Unmovable::new("hello".to_string());</span>
<span class="doccomment">//! // The pointer should point to the correct location,</span>
<span class="doccomment">//! // so long as the struct hasn't moved.</span>
<span class="doccomment">//! // Meanwhile, we are free to move the pointer around.</span>
<span class="doccomment">//! # #[allow(unused_mut)]</span>
<span class="doccomment">//! let mut still_unmoved = unmoved;</span>
<span class="doccomment">//! assert_eq!(still_unmoved.slice, NonNull::from(&still_unmoved.data));</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! // Since our type doesn't implement Unpin, this will fail to compile:</span>
<span class="doccomment">//! // let mut new_unmoved = Unmovable::new("world".to_string());</span>
<span class="doccomment">//! // std::mem::swap(&mut *still_unmoved, &mut *new_unmoved);</span>
<span class="doccomment">//! ```</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! # Example: intrusive doubly-linked list</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! In an intrusive doubly-linked list, the collection does not actually allocate</span>
<span class="doccomment">//! the memory for the elements itself. Allocation is controlled by the clients,</span>
<span class="doccomment">//! and elements can live on a stack frame that lives shorter than the collection does.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! To make this work, every element has pointers to its predecessor and successor in</span>
<span class="doccomment">//! the list. Elements can only be added when they are pinned, because moving the elements</span>
<span class="doccomment">//! around would invalidate the pointers. Moreover, the `Drop` implementation of a linked</span>
<span class="doccomment">//! list element will patch the pointers of its predecessor and successor to remove itself</span>
<span class="doccomment">//! from the list.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! Crucially, we have to be able to rely on `drop` being called. If an element</span>
<span class="doccomment">//! could be deallocated or otherwise invalidated without calling `drop`, the pointers into it</span>
<span class="doccomment">//! from its neighbouring elements would become invalid, which would break the data structure.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! Therefore, pinning also comes with a `drop`-related guarantee.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! # `Drop` guarantee</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! The purpose of pinning is to be able to rely on the placement of some data in memory.</span>
<span class="doccomment">//! To make this work, not just moving the data is restricted; deallocating, repurposing, or</span>
<span class="doccomment">//! otherwise invalidating the memory used to store the data is restricted, too.</span>
<span class="doccomment">//! Concretely, for pinned data you have to maintain the invariant</span>
<span class="doccomment">//! that *its memory will not get invalidated from the moment it gets pinned until</span>
<span class="doccomment">//! when `drop` is called*. Memory can be invalidated by deallocation, but also by</span>
<span class="doccomment">//! replacing a [`Some(v)`] by [`None`], or calling [`Vec::set_len`] to "kill" some elements</span>
<span class="doccomment">//! off of a vector.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! This is exactly the kind of guarantee that the intrusive linked list from the previous</span>
<span class="doccomment">//! section needs to function correctly.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! Notice that this guarantee does *not* mean that memory does not leak! It is still</span>
<span class="doccomment">//! completely okay not to ever call `drop` on a pinned element (e.g., you can still</span>
<span class="doccomment">//! call [`mem::forget`] on a `Pin<Box<T>>`). In the example of the doubly-linked</span>
<span class="doccomment">//! list, that element would just stay in the list. However you may not free or reuse the storage</span>
<span class="doccomment">//! *without calling `drop`*.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! # `Drop` implementation</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! If your type uses pinning (such as the two examples above), you have to be careful</span>
<span class="doccomment">//! when implementing `Drop`. The `drop` function takes `&mut self`, but this</span>
<span class="doccomment">//! is called *even if your type was previously pinned*! It is as if the</span>
<span class="doccomment">//! compiler automatically called `get_unchecked_mut`.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! This can never cause a problem in safe code because implementing a type that relies on pinning</span>
<span class="doccomment">//! requires unsafe code, but be aware that deciding to make use of pinning</span>
<span class="doccomment">//! in your type (for example by implementing some operation on `Pin<&[mut] Self>`)</span>
<span class="doccomment">//! has consequences for your `Drop` implementation as well: if an element</span>
<span class="doccomment">//! of your type could have been pinned, you must treat Drop as implicitly taking</span>
<span class="doccomment">//! `Pin<&mut Self>`.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! In particular, if your type is `#[repr(packed)]`, the compiler will automatically</span>
<span class="doccomment">//! move fields around to be able to drop them. As a consequence, you cannot use</span>
<span class="doccomment">//! pinning with a `#[repr(packed)]` type.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! # Projections and Structural Pinning</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! One interesting question arises when considering the interaction of pinning and</span>
<span class="doccomment">//! the fields of a struct. When can a struct have a "pinning projection", i.e.,</span>
<span class="doccomment">//! an operation with type `fn(Pin<&[mut] Struct>) -> Pin<&[mut] Field>`?</span>
<span class="doccomment">//! In a similar vein, when can a generic wrapper type (such as `Vec<T>`, `Box<T>`, or `RefCell<T>`)</span>
<span class="doccomment">//! have an operation with type `fn(Pin<&[mut] Wrapper<T>>) -> Pin<&[mut] T>`?</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! Having a pinning projection for some field means that pinning is "structural":</span>
<span class="doccomment">//! when the wrapper is pinned, the field must be considered pinned, too.</span>
<span class="doccomment">//! After all, the pinning projection lets us get a `Pin<&[mut] Field>`.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! However, structural pinning comes with a few extra requirements, so not all</span>
<span class="doccomment">//! wrappers can be structural and hence not all wrappers can offer pinning projections:</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! 1. The wrapper must only be [`Unpin`] if all the structural fields are</span>
<span class="doccomment">//! `Unpin`. This is the default, but `Unpin` is a safe trait, so as the author of</span>
<span class="doccomment">//! the wrapper it is your responsibility *not* to add something like</span>
<span class="doccomment">//! `impl<T> Unpin for Wrapper<T>`. (Notice that adding a projection operation</span>
<span class="doccomment">//! requires unsafe code, so the fact that `Unpin` is a safe trait does not break</span>
<span class="doccomment">//! the principle that you only have to worry about any of this if you use `unsafe`.)</span>
<span class="doccomment">//! 2. The destructor of the wrapper must not move structural fields out of its argument. This</span>
<span class="doccomment">//! is the exact point that was raised in the [previous section][drop-impl]: `drop` takes</span>
<span class="doccomment">//! `&mut self`, but the wrapper (and hence its fields) might have been pinned before.</span>
<span class="doccomment">//! You have to guarantee that you do not move a field inside your `Drop` implementation.</span>
<span class="doccomment">//! In particular, as explained previously, this means that your wrapper type must *not*</span>
<span class="doccomment">//! be `#[repr(packed)]`.</span>
<span class="doccomment">//! 3. You must make sure that you uphold the [`Drop` guarantee][drop-guarantee]:</span>
<span class="doccomment">//! once your wrapper is pinned, the memory that contains the</span>
<span class="doccomment">//! content is not overwritten or deallocated without calling the content's destructors.</span>
<span class="doccomment">//! This can be tricky, as witnessed by `VecDeque<T>`: the destructor of `VecDeque<T>` can fail</span>
<span class="doccomment">//! to call `drop` on all elements if one of the destructors panics. This violates the</span>
<span class="doccomment">//! `Drop` guarantee, because it can lead to elements being deallocated without</span>
<span class="doccomment">//! their destructor being called. (`VecDeque` has no pinning projections, so this</span>
<span class="doccomment">//! does not cause unsoundness.)</span>
<span class="doccomment">//! 4. You must not offer any other operations that could lead to data being moved out of</span>
<span class="doccomment">//! the fields when your type is pinned. For example, if the wrapper contains an</span>
<span class="doccomment">//! `Option<T>` and there is a `take`-like operation with type</span>
<span class="doccomment">//! `fn(Pin<&mut Wrapper<T>>) -> Option<T>`,</span>
<span class="doccomment">//! that operation can be used to move a `T` out of a pinned `Wrapper<T>` -- which means</span>
<span class="doccomment">//! pinning cannot be structural.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! For a more complex example of moving data out of a pinned type, imagine if `RefCell<T>`</span>
<span class="doccomment">//! had a method `fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T>`.</span>
<span class="doccomment">//! Then we could do the following:</span>
<span class="doccomment">//! ```compile_fail</span>
<span class="doccomment">//! fn exploit_ref_cell<T>(rc: Pin<&mut RefCell<T>>) {</span>
<span class="doccomment">//! { let p = rc.as_mut().get_pin_mut(); } // Here we get pinned access to the `T`.</span>
<span class="doccomment">//! let rc_shr: &RefCell<T> = rc.into_ref().get_ref();</span>
<span class="doccomment">//! let b = rc_shr.borrow_mut();</span>
<span class="doccomment">//! let content = &mut *b; // And here we have `&mut T` to the same data.</span>
<span class="doccomment">//! }</span>
<span class="doccomment">//! ```</span>
<span class="doccomment">//! This is catastrophic, it means we can first pin the content of the `RefCell<T>`</span>
<span class="doccomment">//! (using `RefCell::get_pin_mut`) and then move that content using the mutable</span>
<span class="doccomment">//! reference we got later.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! For a type like `Vec<T>`, both possibilites (structural pinning or not) make sense,</span>
<span class="doccomment">//! and the choice is up to the author. A `Vec<T>` with structural pinning could</span>
<span class="doccomment">//! have `get_pin`/`get_pin_mut` projections. However, it could *not* allow calling</span>
<span class="doccomment">//! `pop` on a pinned `Vec<T>` because that would move the (structurally pinned) contents!</span>
<span class="doccomment">//! Nor could it allow `push`, which might reallocate and thus also move the contents.</span>
<span class="doccomment">//! A `Vec<T>` without structural pinning could `impl<T> Unpin for Vec<T>`, because the contents</span>
<span class="doccomment">//! are never pinned and the `Vec<T>` itself is fine with being moved as well.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! In the standard library, pointer types generally do not have structural pinning,</span>
<span class="doccomment">//! and thus they do not offer pinning projections. This is why `Box<T>: Unpin` holds for all `T`.</span>
<span class="doccomment">//! It makes sense to do this for pointer types, because moving the `Box<T>`</span>
<span class="doccomment">//! does not actually move the `T`: the `Box<T>` can be freely movable (aka `Unpin`) even if the `T`</span>
<span class="doccomment">//! is not. In fact, even `Pin<Box<T>>` and `Pin<&mut T>` are always `Unpin` themselves,</span>
<span class="doccomment">//! for the same reason: their contents (the `T`) are pinned, but the pointers themselves</span>
<span class="doccomment">//! can be moved without moving the pinned data. For both `Box<T>` and `Pin<Box<T>>`,</span>
<span class="doccomment">//! whether the content is pinned is entirely independent of whether the pointer is</span>
<span class="doccomment">//! pinned, meaning pinning is *not* structural.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! [`Pin<P>`]: struct.Pin.html</span>
<span class="doccomment">//! [`Unpin`]: ../../std/marker/trait.Unpin.html</span>
<span class="doccomment">//! [`Deref`]: ../../std/ops/trait.Deref.html</span>
<span class="doccomment">//! [`DerefMut`]: ../../std/ops/trait.DerefMut.html</span>
<span class="doccomment">//! [`mem::swap`]: ../../std/mem/fn.swap.html</span>
<span class="doccomment">//! [`mem::forget`]: ../../std/mem/fn.forget.html</span>
<span class="doccomment">//! [`Box<T>`]: ../../std/boxed/struct.Box.html</span>
<span class="doccomment">//! [`Vec::set_len`]: ../../std/vec/struct.Vec.html#method.set_len</span>
<span class="doccomment">//! [`None`]: ../../std/option/enum.Option.html#variant.None</span>
<span class="doccomment">//! [`Some(v)`]: ../../std/option/enum.Option.html#variant.Some</span>
<span class="doccomment">//! [drop-impl]: #drop-implementation</span>
<span class="doccomment">//! [drop-guarantee]: #drop-guarantee</span>
<span class="attribute">#![<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="kw">use</span> <span class="ident">fmt</span>;
<span class="kw">use</span> <span class="ident">marker</span>::{<span class="ident">Sized</span>, <span class="ident">Unpin</span>};
<span class="kw">use</span> <span class="ident">cmp</span>::{<span class="self">self</span>, <span class="ident">PartialEq</span>, <span class="ident">PartialOrd</span>};
<span class="kw">use</span> <span class="ident">ops</span>::{<span class="ident">Deref</span>, <span class="ident">DerefMut</span>, <span class="ident">Receiver</span>, <span class="ident">CoerceUnsized</span>, <span class="ident">DispatchFromDyn</span>};
<span class="doccomment">/// A pinned pointer.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This is a wrapper around a kind of pointer which makes that pointer "pin" its</span>
<span class="doccomment">/// value in place, preventing the value referenced by that pointer from being moved</span>
<span class="doccomment">/// unless it implements [`Unpin`].</span>
<span class="doccomment">///</span>
<span class="doccomment">/// See the [`pin` module] documentation for further explanation on pinning.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// [`Unpin`]: ../../std/marker/trait.Unpin.html</span>
<span class="doccomment">/// [`pin` module]: ../../std/pin/index.html</span>
<span class="comment">//</span>
<span class="comment">// Note: the derives below, and the explicit `PartialEq` and `PartialOrd`</span>
<span class="comment">// implementations, are allowed because they all only use `&P`, so they cannot move</span>
<span class="comment">// the value behind `pointer`.</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="attribute">#[<span class="ident">lang</span> <span class="op">=</span> <span class="string">"pin"</span>]</span>
<span class="attribute">#[<span class="ident">fundamental</span>]</span>
<span class="attribute">#[<span class="ident">repr</span>(<span class="ident">transparent</span>)]</span>
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Copy</span>, <span class="ident">Clone</span>, <span class="ident">Hash</span>, <span class="ident">Eq</span>, <span class="ident">Ord</span>)]</span>
<span class="kw">pub</span> <span class="kw">struct</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span> {
<span class="ident">pointer</span>: <span class="ident">P</span>,
}
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin_partialeq_partialord_impl_applicability"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.34.0"</span>)]</span>
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>, <span class="ident">Q</span><span class="op">></span> <span class="ident">PartialEq</span><span class="op"><</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">Q</span><span class="op">>></span> <span class="kw">for</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span>
<span class="kw">where</span>
<span class="ident">P</span>: <span class="ident">PartialEq</span><span class="op"><</span><span class="ident">Q</span><span class="op">></span>,
{
<span class="kw">fn</span> <span class="ident">eq</span>(<span class="kw-2">&</span><span class="self">self</span>, <span class="ident">other</span>: <span class="kw-2">&</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">Q</span><span class="op">></span>) <span class="op">-></span> <span class="ident">bool</span> {
<span class="self">self</span>.<span class="ident">pointer</span> <span class="op">==</span> <span class="ident">other</span>.<span class="ident">pointer</span>
}
<span class="kw">fn</span> <span class="ident">ne</span>(<span class="kw-2">&</span><span class="self">self</span>, <span class="ident">other</span>: <span class="kw-2">&</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">Q</span><span class="op">></span>) <span class="op">-></span> <span class="ident">bool</span> {
<span class="self">self</span>.<span class="ident">pointer</span> <span class="op">!=</span> <span class="ident">other</span>.<span class="ident">pointer</span>
}
}
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin_partialeq_partialord_impl_applicability"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.34.0"</span>)]</span>
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>, <span class="ident">Q</span><span class="op">></span> <span class="ident">PartialOrd</span><span class="op"><</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">Q</span><span class="op">>></span> <span class="kw">for</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span>
<span class="kw">where</span>
<span class="ident">P</span>: <span class="ident">PartialOrd</span><span class="op"><</span><span class="ident">Q</span><span class="op">></span>,
{
<span class="kw">fn</span> <span class="ident">partial_cmp</span>(<span class="kw-2">&</span><span class="self">self</span>, <span class="ident">other</span>: <span class="kw-2">&</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">Q</span><span class="op">></span>) <span class="op">-></span> <span class="prelude-ty">Option</span><span class="op"><</span><span class="ident">cmp</span>::<span class="ident">Ordering</span><span class="op">></span> {
<span class="self">self</span>.<span class="ident">pointer</span>.<span class="ident">partial_cmp</span>(<span class="kw-2">&</span><span class="ident">other</span>.<span class="ident">pointer</span>)
}
<span class="kw">fn</span> <span class="ident">lt</span>(<span class="kw-2">&</span><span class="self">self</span>, <span class="ident">other</span>: <span class="kw-2">&</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">Q</span><span class="op">></span>) <span class="op">-></span> <span class="ident">bool</span> {
<span class="self">self</span>.<span class="ident">pointer</span> <span class="op"><</span> <span class="ident">other</span>.<span class="ident">pointer</span>
}
<span class="kw">fn</span> <span class="ident">le</span>(<span class="kw-2">&</span><span class="self">self</span>, <span class="ident">other</span>: <span class="kw-2">&</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">Q</span><span class="op">></span>) <span class="op">-></span> <span class="ident">bool</span> {
<span class="self">self</span>.<span class="ident">pointer</span> <span class="op"><=</span> <span class="ident">other</span>.<span class="ident">pointer</span>
}
<span class="kw">fn</span> <span class="ident">gt</span>(<span class="kw-2">&</span><span class="self">self</span>, <span class="ident">other</span>: <span class="kw-2">&</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">Q</span><span class="op">></span>) <span class="op">-></span> <span class="ident">bool</span> {
<span class="self">self</span>.<span class="ident">pointer</span> <span class="op">></span> <span class="ident">other</span>.<span class="ident">pointer</span>
}
<span class="kw">fn</span> <span class="ident">ge</span>(<span class="kw-2">&</span><span class="self">self</span>, <span class="ident">other</span>: <span class="kw-2">&</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">Q</span><span class="op">></span>) <span class="op">-></span> <span class="ident">bool</span> {
<span class="self">self</span>.<span class="ident">pointer</span> <span class="op">>=</span> <span class="ident">other</span>.<span class="ident">pointer</span>
}
}
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>: <span class="ident">Deref</span><span class="op">></span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span>
<span class="kw">where</span>
<span class="ident">P</span>::<span class="ident">Target</span>: <span class="ident">Unpin</span>,
{
<span class="doccomment">/// Construct a new `Pin<P>` around a pointer to some data of a type that</span>
<span class="doccomment">/// implements [`Unpin`].</span>
<span class="doccomment">///</span>
<span class="doccomment">/// Unlike `Pin::new_unchecked`, this method is safe because the pointer</span>
<span class="doccomment">/// `P` dereferences to an [`Unpin`] type, which cancels the pinning guarantees.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// [`Unpin`]: ../../std/marker/trait.Unpin.html</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="attribute">#[<span class="ident">inline</span>(<span class="ident">always</span>)]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">new</span>(<span class="ident">pointer</span>: <span class="ident">P</span>) <span class="op">-></span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span> {
<span class="comment">// Safety: the value pointed to is `Unpin`, and so has no requirements</span>
<span class="comment">// around pinning.</span>
<span class="kw">unsafe</span> { <span class="ident">Pin</span>::<span class="ident">new_unchecked</span>(<span class="ident">pointer</span>) }
}
}
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>: <span class="ident">Deref</span><span class="op">></span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span> {
<span class="doccomment">/// Construct a new `Pin<P>` around a reference to some data of a type that</span>
<span class="doccomment">/// may or may not implement `Unpin`.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// If `pointer` dereferences to an `Unpin` type, `Pin::new` should be used</span>
<span class="doccomment">/// instead.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// # Safety</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This constructor is unsafe because we cannot guarantee that the data</span>
<span class="doccomment">/// pointed to by `pointer` is pinned, meaning that the data will not be moved or</span>
<span class="doccomment">/// its storage invalidated until it gets dropped. If the constructed `Pin<P>` does</span>
<span class="doccomment">/// not guarantee that the data `P` points to is pinned, that is a violation of</span>
<span class="doccomment">/// the API contract and may lead to undefined behavior in later (safe) operations.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// By using this method, you are making a promise about the `P::Deref` and</span>
<span class="doccomment">/// `P::DerefMut` implementations, if they exist. Most importantly, they</span>
<span class="doccomment">/// must not move out of their `self` arguments: `Pin::as_mut` and `Pin::as_ref`</span>
<span class="doccomment">/// will call `DerefMut::deref_mut` and `Deref::deref` *on the pinned pointer*</span>
<span class="doccomment">/// and expect these methods to uphold the pinning invariants.</span>
<span class="doccomment">/// Moreover, by calling this method you promise that the reference `P`</span>
<span class="doccomment">/// dereferences to will not be moved out of again; in particular, it</span>
<span class="doccomment">/// must not be possible to obtain a `&mut P::Target` and then</span>
<span class="doccomment">/// move out of that reference (using, for example [`mem::swap`]).</span>
<span class="doccomment">///</span>
<span class="doccomment">/// For example, calling `Pin::new_unchecked` on an `&'a mut T` is unsafe because</span>
<span class="doccomment">/// while you are able to pin it for the given lifetime `'a`, you have no control</span>
<span class="doccomment">/// over whether it is kept pinned once `'a` ends:</span>
<span class="doccomment">/// ```</span>
<span class="doccomment">/// use std::mem;</span>
<span class="doccomment">/// use std::pin::Pin;</span>
<span class="doccomment">///</span>
<span class="doccomment">/// fn move_pinned_ref<T>(mut a: T, mut b: T) {</span>
<span class="doccomment">/// unsafe {</span>
<span class="doccomment">/// let p: Pin<&mut T> = Pin::new_unchecked(&mut a);</span>
<span class="doccomment">/// // This should mean the pointee `a` can never move again.</span>
<span class="doccomment">/// }</span>
<span class="doccomment">/// mem::swap(&mut a, &mut b);</span>
<span class="doccomment">/// // The address of `a` changed to `b`'s stack slot, so `a` got moved even</span>
<span class="doccomment">/// // though we have previously pinned it! We have violated the pinning API contract.</span>
<span class="doccomment">/// }</span>
<span class="doccomment">/// ```</span>
<span class="doccomment">/// A value, once pinned, must remain pinned forever (unless its type implements `Unpin`).</span>
<span class="doccomment">///</span>
<span class="doccomment">/// Similarily, calling `Pin::new_unchecked` on an `Rc<T>` is unsafe because there could be</span>
<span class="doccomment">/// aliases to the same data that are not subject to the pinning restrictions:</span>
<span class="doccomment">/// ```</span>
<span class="doccomment">/// use std::rc::Rc;</span>
<span class="doccomment">/// use std::pin::Pin;</span>
<span class="doccomment">///</span>
<span class="doccomment">/// fn move_pinned_rc<T>(mut x: Rc<T>) {</span>
<span class="doccomment">/// let pinned = unsafe { Pin::new_unchecked(x.clone()) };</span>
<span class="doccomment">/// {</span>
<span class="doccomment">/// let p: Pin<&T> = pinned.as_ref();</span>
<span class="doccomment">/// // This should mean the pointee can never move again.</span>
<span class="doccomment">/// }</span>
<span class="doccomment">/// drop(pinned);</span>
<span class="doccomment">/// let content = Rc::get_mut(&mut x).unwrap();</span>
<span class="doccomment">/// // Now, if `x` was the only reference, we have a mutable reference to</span>
<span class="doccomment">/// // data that we pinned above, which we could use to move it as we have</span>
<span class="doccomment">/// // seen in the previous example. We have violated the pinning API contract.</span>
<span class="doccomment">/// }</span>
<span class="doccomment">/// ```</span>
<span class="doccomment">///</span>
<span class="doccomment">/// [`mem::swap`]: ../../std/mem/fn.swap.html</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="attribute">#[<span class="ident">inline</span>(<span class="ident">always</span>)]</span>
<span class="kw">pub</span> <span class="kw">unsafe</span> <span class="kw">fn</span> <span class="ident">new_unchecked</span>(<span class="ident">pointer</span>: <span class="ident">P</span>) <span class="op">-></span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span> {
<span class="ident">Pin</span> { <span class="ident">pointer</span> }
}
<span class="doccomment">/// Gets a pinned shared reference from this pinned pointer.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This is a generic method to go from `&Pin<Pointer<T>>` to `Pin<&T>`.</span>
<span class="doccomment">/// It is safe because, as part of the contract of `Pin::new_unchecked`,</span>
<span class="doccomment">/// the pointee cannot move after `Pin<Pointer<T>>` got created.</span>
<span class="doccomment">/// "Malicious" implementations of `Pointer::Deref` are likewise</span>
<span class="doccomment">/// ruled out by the contract of `Pin::new_unchecked`.</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="attribute">#[<span class="ident">inline</span>(<span class="ident">always</span>)]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">as_ref</span>(<span class="self">self</span>: <span class="kw-2">&</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span>) <span class="op">-></span> <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="ident">P</span>::<span class="ident">Target</span><span class="op">></span> {
<span class="kw">unsafe</span> { <span class="ident">Pin</span>::<span class="ident">new_unchecked</span>(<span class="kw-2">&</span><span class="kw-2">*</span><span class="self">self</span>.<span class="ident">pointer</span>) }
}
}
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>: <span class="ident">DerefMut</span><span class="op">></span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span> {
<span class="doccomment">/// Gets a pinned mutable reference from this pinned pointer.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This is a generic method to go from `&mut Pin<Pointer<T>>` to `Pin<&mut T>`.</span>
<span class="doccomment">/// It is safe because, as part of the contract of `Pin::new_unchecked`,</span>
<span class="doccomment">/// the pointee cannot move after `Pin<Pointer<T>>` got created.</span>
<span class="doccomment">/// "Malicious" implementations of `Pointer::DerefMut` are likewise</span>
<span class="doccomment">/// ruled out by the contract of `Pin::new_unchecked`.</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="attribute">#[<span class="ident">inline</span>(<span class="ident">always</span>)]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">as_mut</span>(<span class="self">self</span>: <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span>) <span class="op">-></span> <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">P</span>::<span class="ident">Target</span><span class="op">></span> {
<span class="kw">unsafe</span> { <span class="ident">Pin</span>::<span class="ident">new_unchecked</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="kw-2">*</span><span class="self">self</span>.<span class="ident">pointer</span>) }
}
<span class="doccomment">/// Assigns a new value to the memory behind the pinned reference.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This overwrites pinned data, but that is okay: its destructor gets</span>
<span class="doccomment">/// run before being overwritten, so no pinning guarantee is violated.</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="attribute">#[<span class="ident">inline</span>(<span class="ident">always</span>)]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">set</span>(<span class="self">self</span>: <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span>, <span class="ident">value</span>: <span class="ident">P</span>::<span class="ident">Target</span>)
<span class="kw">where</span>
<span class="ident">P</span>::<span class="ident">Target</span>: <span class="ident">Sized</span>,
{
<span class="kw-2">*</span>(<span class="self">self</span>.<span class="ident">pointer</span>) <span class="op">=</span> <span class="ident">value</span>;
}
}
<span class="kw">impl</span><span class="op"><</span><span class="lifetime">'a</span>, <span class="ident">T</span>: <span class="question-mark">?</span><span class="ident">Sized</span><span class="op">></span> <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="ident">T</span><span class="op">></span> {
<span class="doccomment">/// Constructs a new pin by mapping the interior value.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// For example, if you wanted to get a `Pin` of a field of something,</span>
<span class="doccomment">/// you could use this to get access to that field in one line of code.</span>
<span class="doccomment">/// However, there are several gotchas with these "pinning projections";</span>
<span class="doccomment">/// see the [`pin` module] documentation for further details on that topic.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// # Safety</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This function is unsafe. You must guarantee that the data you return</span>
<span class="doccomment">/// will not move so long as the argument value does not move (for example,</span>
<span class="doccomment">/// because it is one of the fields of that value), and also that you do</span>
<span class="doccomment">/// not move out of the argument you receive to the interior function.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// [`pin` module]: ../../std/pin/index.html#projections-and-structural-pinning</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="kw">pub</span> <span class="kw">unsafe</span> <span class="kw">fn</span> <span class="ident">map_unchecked</span><span class="op"><</span><span class="ident">U</span>, <span class="ident">F</span><span class="op">></span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="ident">T</span><span class="op">></span>, <span class="ident">func</span>: <span class="ident">F</span>) <span class="op">-></span> <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="ident">U</span><span class="op">></span> <span class="kw">where</span>
<span class="ident">F</span>: <span class="ident">FnOnce</span>(<span class="kw-2">&</span><span class="ident">T</span>) <span class="op">-></span> <span class="kw-2">&</span><span class="ident">U</span>,
{
<span class="kw">let</span> <span class="ident">pointer</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">*</span><span class="self">self</span>.<span class="ident">pointer</span>;
<span class="kw">let</span> <span class="ident">new_pointer</span> <span class="op">=</span> <span class="ident">func</span>(<span class="ident">pointer</span>);
<span class="ident">Pin</span>::<span class="ident">new_unchecked</span>(<span class="ident">new_pointer</span>)
}
<span class="doccomment">/// Gets a shared reference out of a pin.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This is safe because it is not possible to move out of a shared reference.</span>
<span class="doccomment">/// It may seem like there is an issue here with interior mutability: in fact,</span>
<span class="doccomment">/// it *is* possible to move a `T` out of a `&RefCell<T>`. However, this is</span>
<span class="doccomment">/// not a problem as long as there does not also exist a `Pin<&T>` pointing</span>
<span class="doccomment">/// to the same data, and `RefCell<T>` does not let you create a pinned reference</span>
<span class="doccomment">/// to its contents. See the discussion on ["pinning projections"] for further</span>
<span class="doccomment">/// details.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// Note: `Pin` also implements `Deref` to the target, which can be used</span>
<span class="doccomment">/// to access the inner value. However, `Deref` only provides a reference</span>
<span class="doccomment">/// that lives for as long as the borrow of the `Pin`, not the lifetime of</span>
<span class="doccomment">/// the `Pin` itself. This method allows turning the `Pin` into a reference</span>
<span class="doccomment">/// with the same lifetime as the original `Pin`.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// ["pinning projections"]: ../../std/pin/index.html#projections-and-structural-pinning</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="attribute">#[<span class="ident">inline</span>(<span class="ident">always</span>)]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">get_ref</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="ident">T</span><span class="op">></span>) <span class="op">-></span> <span class="kw-2">&</span><span class="lifetime">'a</span> <span class="ident">T</span> {
<span class="self">self</span>.<span class="ident">pointer</span>
}
}
<span class="kw">impl</span><span class="op"><</span><span class="lifetime">'a</span>, <span class="ident">T</span>: <span class="question-mark">?</span><span class="ident">Sized</span><span class="op">></span> <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="kw-2">mut</span> <span class="ident">T</span><span class="op">></span> {
<span class="doccomment">/// Converts this `Pin<&mut T>` into a `Pin<&T>` with the same lifetime.</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="attribute">#[<span class="ident">inline</span>(<span class="ident">always</span>)]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">into_ref</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="kw-2">mut</span> <span class="ident">T</span><span class="op">></span>) <span class="op">-></span> <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="ident">T</span><span class="op">></span> {
<span class="ident">Pin</span> { <span class="ident">pointer</span>: <span class="self">self</span>.<span class="ident">pointer</span> }
}
<span class="doccomment">/// Gets a mutable reference to the data inside of this `Pin`.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This requires that the data inside this `Pin` is `Unpin`.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// Note: `Pin` also implements `DerefMut` to the data, which can be used</span>
<span class="doccomment">/// to access the inner value. However, `DerefMut` only provides a reference</span>
<span class="doccomment">/// that lives for as long as the borrow of the `Pin`, not the lifetime of</span>
<span class="doccomment">/// the `Pin` itself. This method allows turning the `Pin` into a reference</span>
<span class="doccomment">/// with the same lifetime as the original `Pin`.</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="attribute">#[<span class="ident">inline</span>(<span class="ident">always</span>)]</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">get_mut</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="kw-2">mut</span> <span class="ident">T</span><span class="op">></span>) <span class="op">-></span> <span class="kw-2">&</span><span class="lifetime">'a</span> <span class="kw-2">mut</span> <span class="ident">T</span>
<span class="kw">where</span> <span class="ident">T</span>: <span class="ident">Unpin</span>,
{
<span class="self">self</span>.<span class="ident">pointer</span>
}
<span class="doccomment">/// Gets a mutable reference to the data inside of this `Pin`.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// # Safety</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This function is unsafe. You must guarantee that you will never move</span>
<span class="doccomment">/// the data out of the mutable reference you receive when you call this</span>
<span class="doccomment">/// function, so that the invariants on the `Pin` type can be upheld.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// If the underlying data is `Unpin`, `Pin::get_mut` should be used</span>
<span class="doccomment">/// instead.</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="attribute">#[<span class="ident">inline</span>(<span class="ident">always</span>)]</span>
<span class="kw">pub</span> <span class="kw">unsafe</span> <span class="kw">fn</span> <span class="ident">get_unchecked_mut</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="kw-2">mut</span> <span class="ident">T</span><span class="op">></span>) <span class="op">-></span> <span class="kw-2">&</span><span class="lifetime">'a</span> <span class="kw-2">mut</span> <span class="ident">T</span> {
<span class="self">self</span>.<span class="ident">pointer</span>
}
<span class="doccomment">/// Construct a new pin by mapping the interior value.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// For example, if you wanted to get a `Pin` of a field of something,</span>
<span class="doccomment">/// you could use this to get access to that field in one line of code.</span>
<span class="doccomment">/// However, there are several gotchas with these "pinning projections";</span>
<span class="doccomment">/// see the [`pin` module] documentation for further details on that topic.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// # Safety</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This function is unsafe. You must guarantee that the data you return</span>
<span class="doccomment">/// will not move so long as the argument value does not move (for example,</span>
<span class="doccomment">/// because it is one of the fields of that value), and also that you do</span>
<span class="doccomment">/// not move out of the argument you receive to the interior function.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// [`pin` module]: ../../std/pin/index.html#projections-and-structural-pinning</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="kw">pub</span> <span class="kw">unsafe</span> <span class="kw">fn</span> <span class="ident">map_unchecked_mut</span><span class="op"><</span><span class="ident">U</span>, <span class="ident">F</span><span class="op">></span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="kw-2">mut</span> <span class="ident">T</span><span class="op">></span>, <span class="ident">func</span>: <span class="ident">F</span>) <span class="op">-></span> <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="lifetime">'a</span> <span class="kw-2">mut</span> <span class="ident">U</span><span class="op">></span> <span class="kw">where</span>
<span class="ident">F</span>: <span class="ident">FnOnce</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">T</span>) <span class="op">-></span> <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">U</span>,
{
<span class="kw">let</span> <span class="ident">pointer</span> <span class="op">=</span> <span class="ident">Pin</span>::<span class="ident">get_unchecked_mut</span>(<span class="self">self</span>);
<span class="kw">let</span> <span class="ident">new_pointer</span> <span class="op">=</span> <span class="ident">func</span>(<span class="ident">pointer</span>);
<span class="ident">Pin</span>::<span class="ident">new_unchecked</span>(<span class="ident">new_pointer</span>)
}
}
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>: <span class="ident">Deref</span><span class="op">></span> <span class="ident">Deref</span> <span class="kw">for</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span> {
<span class="kw">type</span> <span class="ident">Target</span> <span class="op">=</span> <span class="ident">P</span>::<span class="ident">Target</span>;
<span class="kw">fn</span> <span class="ident">deref</span>(<span class="kw-2">&</span><span class="self">self</span>) <span class="op">-></span> <span class="kw-2">&</span><span class="ident">P</span>::<span class="ident">Target</span> {
<span class="ident">Pin</span>::<span class="ident">get_ref</span>(<span class="ident">Pin</span>::<span class="ident">as_ref</span>(<span class="self">self</span>))
}
}
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>: <span class="ident">DerefMut</span><span class="op">></span> <span class="ident">DerefMut</span> <span class="kw">for</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span>
<span class="kw">where</span>
<span class="ident">P</span>::<span class="ident">Target</span>: <span class="ident">Unpin</span>
{
<span class="kw">fn</span> <span class="ident">deref_mut</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">self</span>) <span class="op">-></span> <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">P</span>::<span class="ident">Target</span> {
<span class="ident">Pin</span>::<span class="ident">get_mut</span>(<span class="ident">Pin</span>::<span class="ident">as_mut</span>(<span class="self">self</span>))
}
}
<span class="attribute">#[<span class="ident">unstable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"receiver_trait"</span>, <span class="ident">issue</span> <span class="op">=</span> <span class="string">"0"</span>)]</span>
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>: <span class="ident">Receiver</span><span class="op">></span> <span class="ident">Receiver</span> <span class="kw">for</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span> {}
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>: <span class="ident">fmt</span>::<span class="ident">Debug</span><span class="op">></span> <span class="ident">fmt</span>::<span class="ident">Debug</span> <span class="kw">for</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span> {
<span class="kw">fn</span> <span class="ident">fmt</span>(<span class="kw-2">&</span><span class="self">self</span>, <span class="ident">f</span>: <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">fmt</span>::<span class="ident">Formatter</span>) <span class="op">-></span> <span class="ident">fmt</span>::<span class="prelude-ty">Result</span> {
<span class="ident">fmt</span>::<span class="ident">Debug</span>::<span class="ident">fmt</span>(<span class="kw-2">&</span><span class="self">self</span>.<span class="ident">pointer</span>, <span class="ident">f</span>)
}
}
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>: <span class="ident">fmt</span>::<span class="ident">Display</span><span class="op">></span> <span class="ident">fmt</span>::<span class="ident">Display</span> <span class="kw">for</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span> {
<span class="kw">fn</span> <span class="ident">fmt</span>(<span class="kw-2">&</span><span class="self">self</span>, <span class="ident">f</span>: <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">fmt</span>::<span class="ident">Formatter</span>) <span class="op">-></span> <span class="ident">fmt</span>::<span class="prelude-ty">Result</span> {
<span class="ident">fmt</span>::<span class="ident">Display</span>::<span class="ident">fmt</span>(<span class="kw-2">&</span><span class="self">self</span>.<span class="ident">pointer</span>, <span class="ident">f</span>)
}
}
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>: <span class="ident">fmt</span>::<span class="ident">Pointer</span><span class="op">></span> <span class="ident">fmt</span>::<span class="ident">Pointer</span> <span class="kw">for</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span> {
<span class="kw">fn</span> <span class="ident">fmt</span>(<span class="kw-2">&</span><span class="self">self</span>, <span class="ident">f</span>: <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">fmt</span>::<span class="ident">Formatter</span>) <span class="op">-></span> <span class="ident">fmt</span>::<span class="prelude-ty">Result</span> {
<span class="ident">fmt</span>::<span class="ident">Pointer</span>::<span class="ident">fmt</span>(<span class="kw-2">&</span><span class="self">self</span>.<span class="ident">pointer</span>, <span class="ident">f</span>)
}
}
<span class="comment">// Note: this means that any impl of `CoerceUnsized` that allows coercing from</span>
<span class="comment">// a type that impls `Deref<Target=impl !Unpin>` to a type that impls</span>
<span class="comment">// `Deref<Target=Unpin>` is unsound. Any such impl would probably be unsound</span>
<span class="comment">// for other reasons, though, so we just need to take care not to allow such</span>
<span class="comment">// impls to land in std.</span>
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="kw">impl</span><span class="op"><</span><span class="ident">P</span>, <span class="ident">U</span><span class="op">></span> <span class="ident">CoerceUnsized</span><span class="op"><</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">U</span><span class="op">>></span> <span class="kw">for</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span>
<span class="kw">where</span>
<span class="ident">P</span>: <span class="ident">CoerceUnsized</span><span class="op"><</span><span class="ident">U</span><span class="op">></span>,
{}
<span class="attribute">#[<span class="ident">stable</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"pin"</span>, <span class="ident">since</span> <span class="op">=</span> <span class="string">"1.33.0"</span>)]</span>
<span class="kw">impl</span><span class="op"><</span><span class="lifetime">'a</span>, <span class="ident">P</span>, <span class="ident">U</span><span class="op">></span> <span class="ident">DispatchFromDyn</span><span class="op"><</span><span class="ident">Pin</span><span class="op"><</span><span class="ident">U</span><span class="op">>></span> <span class="kw">for</span> <span class="ident">Pin</span><span class="op"><</span><span class="ident">P</span><span class="op">></span>
<span class="kw">where</span>
<span class="ident">P</span>: <span class="ident">DispatchFromDyn</span><span class="op"><</span><span class="ident">U</span><span class="op">></span>,
{}
</pre></div>
</section><section id="search" class="content hidden"></section><section class="footer"></section><aside id="help" class="hidden"><div><h1 class="hidden">Help</h1><div class="shortcuts"><h2>Keyboard Shortcuts</h2><dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd><dt><kbd>S</kbd></dt><dd>Focus the search field</dd><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd><dt><kbd>↹</kbd></dt><dd>Switch tab</dd><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd><dt><kbd>+</kbd></dt><dd>Expand all sections</dd><dt><kbd>-</kbd></dt><dd>Collapse all sections</dd></dl></div><div class="infos"><h2>Search Tricks</h2><p>Prefix searches with a type followed by a colon (e.g., <code>fn:</code>) to restrict the search to a given type.</p><p>Accepted types are: <code>fn</code>, <code>mod</code>, <code>struct</code>, <code>enum</code>, <code>trait</code>, <code>type</code>, <code>macro</code>, and <code>const</code>.</p><p>Search functions by type signature (e.g., <code>vec -> usize</code> or <code>* -> vec</code>)</p><p>Search multiple things at once by splitting your query with comma (e.g., <code>str,u8</code> or <code>String,struct:Vec,test</code>)</p></div></div></aside><script>window.rootPath = "../../";window.currentCrate = "core";</script><script src="../../aliases.js"></script><script src="../../main1.35.0.js"></script><script src="../../source-script1.35.0.js"></script><script src="../../source-files.js"></script><script defer src="../../search-index.js"></script></body></html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
0c2243f8a1696816431e7210e991fa52
>
files
>
13930
