Add generated documentation
This commit is contained in:
6
doc/pin_project_lite/all.html
Normal file
6
doc/pin_project_lite/all.html
Normal file
@@ -0,0 +1,6 @@
|
||||
<!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="List of all items in this crate"><meta name="keywords" content="rust, rustlang, rust-lang"><title>List of all items in this crate</title><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="../light.css" id="themeStyle"><link rel="stylesheet" type="text/css" href="../dark.css" disabled ><link rel="stylesheet" type="text/css" href="../ayu.css" disabled ><script id="default-settings"></script><script src="../storage.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="icon" type="image/svg+xml" href="../favicon.svg">
|
||||
<link rel="alternate icon" type="image/png" href="../favicon-16x16.png">
|
||||
<link rel="alternate icon" type="image/png" href="../favicon-32x32.png"><style type="text/css">#crate-search{background-image:url("../down-arrow.svg");}</style></head><body class="rustdoc mod"><!--[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='../pin_project_lite/index.html'><div class='logo-container rust-logo'><img src='../rust-logo.png' alt='logo'></div></a><p class="location">Crate pin_project_lite</p><div class="block version"><p>Version 0.2.0</p></div><a id="all-types" href="index.html"><p>Back to index</p></a></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu"><img src="../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices" role="menu"></div></div><script src="../theme.js"></script><nav class="sub"><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" disabled autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><span class="help-button">?</span>
|
||||
<a id="settings-menu" href="../settings.html"><img src="../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class="fqn"><span class="out-of-band"><span id="render-detail"><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">−</span>]</a></span>
|
||||
</span>
|
||||
<span class="in-band">List of all items</span></h1><h3 id="Macros">Macros</h3><ul class="macros docblock"><li><a href="macro.pin_project.html">pin_project</a></li></ul></section><section id="search" class="content hidden"></section><section class="footer"></section><script>window.rootPath = "../";window.currentCrate = "pin_project_lite";</script><script src="../main.js"></script><script defer src="../search-index.js"></script></body></html>
|
||||
69
doc/pin_project_lite/index.html
Normal file
69
doc/pin_project_lite/index.html
Normal file
@@ -0,0 +1,69 @@
|
||||
<!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="API documentation for the Rust `pin_project_lite` crate."><meta name="keywords" content="rust, rustlang, rust-lang, pin_project_lite"><title>pin_project_lite - Rust</title><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="../light.css" id="themeStyle"><link rel="stylesheet" type="text/css" href="../dark.css" disabled ><link rel="stylesheet" type="text/css" href="../ayu.css" disabled ><script id="default-settings"></script><script src="../storage.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="icon" type="image/svg+xml" href="../favicon.svg">
|
||||
<link rel="alternate icon" type="image/png" href="../favicon-16x16.png">
|
||||
<link rel="alternate icon" type="image/png" href="../favicon-32x32.png"><style type="text/css">#crate-search{background-image:url("../down-arrow.svg");}</style></head><body class="rustdoc mod"><!--[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='../pin_project_lite/index.html'><div class='logo-container rust-logo'><img src='../rust-logo.png' alt='logo'></div></a><p class="location">Crate pin_project_lite</p><div class="block version"><p>Version 0.2.0</p></div><div class="sidebar-elems"><a id="all-types" href="all.html"><p>See all pin_project_lite's items</p></a><div class="block items"><ul><li><a href="#macros">Macros</a></li></ul></div><p class="location"></p><script>window.sidebarCurrent = {name: "pin_project_lite", ty: "mod", relpath: "../"};</script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu"><img src="../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices" role="menu"></div></div><script src="../theme.js"></script><nav class="sub"><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" disabled autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><span class="help-button">?</span>
|
||||
<a id="settings-menu" href="../settings.html"><img src="../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class="fqn"><span class="out-of-band"><span id="render-detail"><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">−</span>]</a></span><a class="srclink" href="../src/pin_project_lite/lib.rs.html#1-1273" title="goto source code">[src]</a></span><span class="in-band">Crate <a class="mod" href="">pin_project_lite</a></span></h1><div class="docblock"><p>A lightweight version of <a href="https://github.com/taiki-e/pin-project">pin-project</a> written with declarative macros.</p>
|
||||
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
|
||||
<p><a href="../pin_project_lite/macro.pin_project.html" title="pin_project!"><code>pin_project!</code></a> macro creates a projection type covering all the fields of struct.</p>
|
||||
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">use</span> <span class="ident">pin_project_lite</span>::<span class="ident">pin_project</span>;
|
||||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">pin</span>::<span class="ident">Pin</span>;
|
||||
|
||||
<span class="macro">pin_project</span><span class="macro">!</span> {
|
||||
<span class="kw">struct</span> <span class="ident">Struct</span><span class="op"><</span><span class="ident">T</span>, <span class="ident">U</span><span class="op">></span> {
|
||||
<span class="attribute">#[<span class="ident">pin</span>]</span>
|
||||
<span class="ident">pinned</span>: <span class="ident">T</span>,
|
||||
<span class="ident">unpinned</span>: <span class="ident">U</span>,
|
||||
}
|
||||
}
|
||||
|
||||
<span class="kw">impl</span><span class="op"><</span><span class="ident">T</span>, <span class="ident">U</span><span class="op">></span> <span class="ident">Struct</span><span class="op"><</span><span class="ident">T</span>, <span class="ident">U</span><span class="op">></span> {
|
||||
<span class="kw">fn</span> <span class="ident">method</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">Self</span><span class="op">></span>) {
|
||||
<span class="kw">let</span> <span class="ident">this</span> <span class="op">=</span> <span class="self">self</span>.<span class="ident">project</span>();
|
||||
<span class="kw">let</span> <span class="kw">_</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">T</span><span class="op">></span> <span class="op">=</span> <span class="ident">this</span>.<span class="ident">pinned</span>; <span class="comment">// Pinned reference to the field</span>
|
||||
<span class="kw">let</span> <span class="kw">_</span>: <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">U</span> <span class="op">=</span> <span class="ident">this</span>.<span class="ident">unpinned</span>; <span class="comment">// Normal reference to the field</span>
|
||||
}
|
||||
}</pre></div>
|
||||
<p>To use <a href="../pin_project_lite/macro.pin_project.html" title="pin_project!"><code>pin_project!</code></a> on enums, you need to name the projection type
|
||||
returned from the method.</p>
|
||||
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">use</span> <span class="ident">pin_project_lite</span>::<span class="ident">pin_project</span>;
|
||||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">pin</span>::<span class="ident">Pin</span>;
|
||||
|
||||
<span class="macro">pin_project</span><span class="macro">!</span> {
|
||||
<span class="attribute">#[<span class="ident">project</span> <span class="op">=</span> <span class="ident">EnumProj</span>]</span>
|
||||
<span class="kw">enum</span> <span class="ident">Enum</span><span class="op"><</span><span class="ident">T</span>, <span class="ident">U</span><span class="op">></span> {
|
||||
<span class="ident">Variant</span> { <span class="attribute">#[<span class="ident">pin</span>]</span> <span class="ident">pinned</span>: <span class="ident">T</span>, <span class="ident">unpinned</span>: <span class="ident">U</span> },
|
||||
}
|
||||
}
|
||||
|
||||
<span class="kw">impl</span><span class="op"><</span><span class="ident">T</span>, <span class="ident">U</span><span class="op">></span> <span class="ident">Enum</span><span class="op"><</span><span class="ident">T</span>, <span class="ident">U</span><span class="op">></span> {
|
||||
<span class="kw">fn</span> <span class="ident">method</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">Self</span><span class="op">></span>) {
|
||||
<span class="kw">match</span> <span class="self">self</span>.<span class="ident">project</span>() {
|
||||
<span class="ident">EnumProj</span>::<span class="ident">Variant</span> { <span class="ident">pinned</span>, <span class="ident">unpinned</span> } <span class="op">=</span><span class="op">></span> {
|
||||
<span class="kw">let</span> <span class="kw">_</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">T</span><span class="op">></span> <span class="op">=</span> <span class="ident">pinned</span>;
|
||||
<span class="kw">let</span> <span class="kw">_</span>: <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">U</span> <span class="op">=</span> <span class="ident">unpinned</span>;
|
||||
}
|
||||
}
|
||||
}
|
||||
}</pre></div>
|
||||
<h1 id="pin-project-vs-pin-project-lite" class="section-header"><a href="#pin-project-vs-pin-project-lite">pin-project vs pin-project-lite</a></h1>
|
||||
<p>Here are some similarities and differences compared to <a href="https://github.com/taiki-e/pin-project">pin-project</a>.</p>
|
||||
<h2 id="similar-safety" class="section-header"><a href="#similar-safety">Similar: Safety</a></h2>
|
||||
<p>pin-project-lite guarantees safety in much the same way as <a href="https://github.com/taiki-e/pin-project">pin-project</a>. Both are completely safe unless you write other unsafe code.</p>
|
||||
<h2 id="different-minimal-design" class="section-header"><a href="#different-minimal-design">Different: Minimal design</a></h2>
|
||||
<p>This library does not tackle as expansive of a range of use cases as <a href="https://github.com/taiki-e/pin-project">pin-project</a> does. If your use case is not already covered, please use <a href="https://github.com/taiki-e/pin-project">pin-project</a>.</p>
|
||||
<h2 id="different-no-proc-macro-related-dependencies" class="section-header"><a href="#different-no-proc-macro-related-dependencies">Different: No proc-macro related dependencies</a></h2>
|
||||
<p>This is the <strong>only</strong> reason to use this crate. However, <strong>if you already have proc-macro related dependencies in your crate's dependency graph, there is no benefit from using this crate.</strong> (Note: There is almost no difference in the amount of code generated between <a href="https://github.com/taiki-e/pin-project">pin-project</a> and pin-project-lite.)</p>
|
||||
<h2 id="different-no-useful-error-messages" class="section-header"><a href="#different-no-useful-error-messages">Different: No useful error messages</a></h2>
|
||||
<p>This macro does not handle any invalid input. So error messages are not to be useful in most cases. If you do need useful error messages, then upon error you can pass the same input to <a href="https://github.com/taiki-e/pin-project">pin-project</a> to receive a helpful description of the compile error.</p>
|
||||
<h2 id="different-no-support-for-custom-drop-implementation" class="section-header"><a href="#different-no-support-for-custom-drop-implementation">Different: No support for custom Drop implementation</a></h2>
|
||||
<p>pin-project supports this by <a href="https://docs.rs/pin-project/1/pin_project/attr.pin_project.html#pinned_drop"><code>#[pinned_drop]</code></a>.</p>
|
||||
<h2 id="different-no-support-for-custom-unpin-implementation" class="section-header"><a href="#different-no-support-for-custom-unpin-implementation">Different: No support for custom Unpin implementation</a></h2>
|
||||
<p>pin-project supports this by <a href="https://docs.rs/pin-project/1/pin_project/attr.pin_project.html#unsafeunpin"><code>UnsafeUnpin</code></a> and <a href="https://docs.rs/pin-project/1/pin_project/attr.pin_project.html#unpin"><code>!Unpin</code></a>.</p>
|
||||
<h2 id="different-no-support-for-tuple-structs-and-tuple-variants" class="section-header"><a href="#different-no-support-for-tuple-structs-and-tuple-variants">Different: No support for tuple structs and tuple variants</a></h2>
|
||||
<p>pin-project supports this.</p>
|
||||
</div><h2 id="macros" class="section-header"><a href="#macros">Macros</a></h2>
|
||||
<table><tr class="module-item"><td><a class="macro" href="macro.pin_project.html" title="pin_project_lite::pin_project macro">pin_project</a></td><td class="docblock-short"><p>A macro that creates a projection type covering all the fields of struct.</p>
|
||||
</td></tr></table></section><section id="search" class="content hidden"></section><section class="footer"></section><script>window.rootPath = "../";window.currentCrate = "pin_project_lite";</script><script src="../main.js"></script><script defer src="../search-index.js"></script></body></html>
|
||||
10
doc/pin_project_lite/macro.pin_project!.html
Normal file
10
doc/pin_project_lite/macro.pin_project!.html
Normal file
@@ -0,0 +1,10 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta http-equiv="refresh" content="0;URL=macro.pin_project.html">
|
||||
</head>
|
||||
<body>
|
||||
<p>Redirecting to <a href="macro.pin_project.html">macro.pin_project.html</a>...</p>
|
||||
<script>location.replace("macro.pin_project.html" + location.search + location.hash);</script>
|
||||
</body>
|
||||
</html>
|
||||
171
doc/pin_project_lite/macro.pin_project.html
Normal file
171
doc/pin_project_lite/macro.pin_project.html
Normal file
@@ -0,0 +1,171 @@
|
||||
<!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="API documentation for the Rust `pin_project` macro in crate `pin_project_lite`."><meta name="keywords" content="rust, rustlang, rust-lang, pin_project"><title>pin_project_lite::pin_project - Rust</title><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="../light.css" id="themeStyle"><link rel="stylesheet" type="text/css" href="../dark.css" disabled ><link rel="stylesheet" type="text/css" href="../ayu.css" disabled ><script id="default-settings"></script><script src="../storage.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="icon" type="image/svg+xml" href="../favicon.svg">
|
||||
<link rel="alternate icon" type="image/png" href="../favicon-16x16.png">
|
||||
<link rel="alternate icon" type="image/png" href="../favicon-32x32.png"><style type="text/css">#crate-search{background-image:url("../down-arrow.svg");}</style></head><body class="rustdoc macro"><!--[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='../pin_project_lite/index.html'><div class='logo-container rust-logo'><img src='../rust-logo.png' alt='logo'></div></a><div class="sidebar-elems"><p class="location"><a href="index.html">pin_project_lite</a></p><script>window.sidebarCurrent = {name: "pin_project", ty: "macro", relpath: ""};</script><script defer src="sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu"><img src="../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices" role="menu"></div></div><script src="../theme.js"></script><nav class="sub"><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" disabled autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><span class="help-button">?</span>
|
||||
<a id="settings-menu" href="../settings.html"><img src="../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class="fqn"><span class="out-of-band"><span id="render-detail"><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">−</span>]</a></span><a class="srclink" href="../src/pin_project_lite/lib.rs.html#294-338" title="goto source code">[src]</a></span><span class="in-band">Macro <a href="index.html">pin_project_lite</a>::<wbr><a class="macro" href="">pin_project</a></span></h1><div class="docblock type-decl hidden-by-usual-hider"><div class="example-wrap"><pre class="rust macro">
|
||||
<span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">pin_project</span> {
|
||||
(
|
||||
$(<span class="attribute">#[<span class="ident">doc</span> $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">doc</span>:<span class="ident">tt</span>)<span class="kw-2">*</span>]</span>)<span class="op">*</span>
|
||||
<span class="attribute">#[<span class="ident">project</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">proj_mut_ident</span>:<span class="ident">ident</span>]</span>
|
||||
<span class="attribute">#[<span class="ident">project_ref</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">proj_ref_ident</span>:<span class="ident">ident</span>]</span>
|
||||
$(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">tt</span>:<span class="ident">tt</span>)<span class="op">*</span>
|
||||
) <span class="op">=</span><span class="op">></span> { ... };
|
||||
(
|
||||
$(<span class="attribute">#[<span class="ident">doc</span> $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">doc</span>:<span class="ident">tt</span>)<span class="kw-2">*</span>]</span>)<span class="op">*</span>
|
||||
<span class="attribute">#[<span class="ident">project</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">proj_mut_ident</span>:<span class="ident">ident</span>]</span>
|
||||
$(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">tt</span>:<span class="ident">tt</span>)<span class="op">*</span>
|
||||
) <span class="op">=</span><span class="op">></span> { ... };
|
||||
(
|
||||
$(<span class="attribute">#[<span class="ident">doc</span> $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">doc</span>:<span class="ident">tt</span>)<span class="kw-2">*</span>]</span>)<span class="op">*</span>
|
||||
<span class="attribute">#[<span class="ident">project_ref</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">proj_ref_ident</span>:<span class="ident">ident</span>]</span>
|
||||
$(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">tt</span>:<span class="ident">tt</span>)<span class="op">*</span>
|
||||
) <span class="op">=</span><span class="op">></span> { ... };
|
||||
(
|
||||
$(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">tt</span>:<span class="ident">tt</span>)<span class="op">*</span>
|
||||
) <span class="op">=</span><span class="op">></span> { ... };
|
||||
}</pre></div>
|
||||
</div><div class="docblock"><p>A macro that creates a projection type covering all the fields of struct.</p>
|
||||
<p>This macro creates a projection type according to the following rules:</p>
|
||||
<ul>
|
||||
<li>For the field that uses <code>#[pin]</code> attribute, makes the pinned reference to the field.</li>
|
||||
<li>For the other fields, makes the unpinned reference to the field.</li>
|
||||
</ul>
|
||||
<p>And the following methods are implemented on the original type:</p>
|
||||
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">fn</span> <span class="ident">project</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">Self</span><span class="op">></span>) <span class="op">-</span><span class="op">></span> <span class="ident">Projection</span><span class="op"><</span><span class="lifetime">'_</span><span class="op">></span>;
|
||||
<span class="kw">fn</span> <span class="ident">project_ref</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="self">Self</span><span class="op">></span>) <span class="op">-</span><span class="op">></span> <span class="ident">ProjectionRef</span><span class="op"><</span><span class="lifetime">'_</span><span class="op">></span>;</pre></div>
|
||||
<p>By passing an attribute with the same name as the method to the macro,
|
||||
you can name the projection type returned from the method. This allows you
|
||||
to use pattern matching on the projected types.</p>
|
||||
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="macro">pin_project</span><span class="macro">!</span> {
|
||||
<span class="attribute">#[<span class="ident">project</span> <span class="op">=</span> <span class="ident">EnumProj</span>]</span>
|
||||
<span class="kw">enum</span> <span class="ident">Enum</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
|
||||
<span class="ident">Variant</span> { <span class="attribute">#[<span class="ident">pin</span>]</span> <span class="ident">field</span>: <span class="ident">T</span> },
|
||||
}
|
||||
}
|
||||
|
||||
<span class="kw">impl</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> <span class="ident">Enum</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
|
||||
<span class="kw">fn</span> <span class="ident">method</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">Self</span><span class="op">></span>) {
|
||||
<span class="kw">let</span> <span class="ident">this</span>: <span class="ident">EnumProj</span><span class="op"><</span><span class="lifetime">'_</span>, <span class="ident">T</span><span class="op">></span> <span class="op">=</span> <span class="self">self</span>.<span class="ident">project</span>();
|
||||
<span class="kw">match</span> <span class="ident">this</span> {
|
||||
<span class="ident">EnumProj</span>::<span class="ident">Variant</span> { <span class="ident">field</span> } <span class="op">=</span><span class="op">></span> {
|
||||
<span class="kw">let</span> <span class="kw">_</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">T</span><span class="op">></span> <span class="op">=</span> <span class="ident">field</span>;
|
||||
}
|
||||
}
|
||||
}
|
||||
}</pre></div>
|
||||
<p>The <code>#[project]</code> (and <code>#[project_ref]</code>) attribute must precede the other
|
||||
attributes except for <code>#[doc]</code>. For example, the following code will not be compiled:</p>
|
||||
|
||||
<div class='information'><div class='tooltip compile_fail'>ⓘ<span class='tooltiptext'>This example deliberately fails to compile</span></div></div><div class="example-wrap"><pre class="rust rust-example-rendered compile_fail">
|
||||
<span class="macro">pin_project</span><span class="macro">!</span> {
|
||||
<span class="doccomment">/// documents (`#[doc]`) can be placed before `#[project]`.</span>
|
||||
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Clone</span>)]</span> <span class="comment">// <--- ERROR</span>
|
||||
<span class="attribute">#[<span class="ident">project</span> <span class="op">=</span> <span class="ident">EnumProj</span>]</span>
|
||||
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span> <span class="comment">// <--- Ok</span>
|
||||
<span class="kw">enum</span> <span class="ident">Enum</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
|
||||
<span class="ident">Variant</span> { <span class="attribute">#[<span class="ident">pin</span>]</span> <span class="ident">field</span>: <span class="ident">T</span> },
|
||||
}
|
||||
}</pre></div>
|
||||
<p>Also, note that the projection types returned by <code>project</code> and <code>project_ref</code> have
|
||||
an additional lifetime at the beginning of generics.</p>
|
||||
<pre><code class="language-text">let this: EnumProj<'_, T> = self.project();
|
||||
^^
|
||||
</code></pre>
|
||||
<p>The visibility of the projected types and projection methods is based on the
|
||||
original type. However, if the visibility of the original type is <code>pub</code>, the
|
||||
visibility of the projected types and the projection methods is downgraded
|
||||
to <code>pub(crate)</code>.</p>
|
||||
<h1 id="safety" class="section-header"><a href="#safety">Safety</a></h1>
|
||||
<p><code>pin_project!</code> macro guarantees safety in much the same way as <a href="https://github.com/taiki-e/pin-project">pin-project</a> crate.
|
||||
Both are completely safe unless you write other unsafe code.</p>
|
||||
<p>See <a href="https://github.com/taiki-e/pin-project">pin-project</a> crate for more details.</p>
|
||||
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">use</span> <span class="ident">pin_project_lite</span>::<span class="ident">pin_project</span>;
|
||||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">pin</span>::<span class="ident">Pin</span>;
|
||||
|
||||
<span class="macro">pin_project</span><span class="macro">!</span> {
|
||||
<span class="kw">struct</span> <span class="ident">Struct</span><span class="op"><</span><span class="ident">T</span>, <span class="ident">U</span><span class="op">></span> {
|
||||
<span class="attribute">#[<span class="ident">pin</span>]</span>
|
||||
<span class="ident">pinned</span>: <span class="ident">T</span>,
|
||||
<span class="ident">unpinned</span>: <span class="ident">U</span>,
|
||||
}
|
||||
}
|
||||
|
||||
<span class="kw">impl</span><span class="op"><</span><span class="ident">T</span>, <span class="ident">U</span><span class="op">></span> <span class="ident">Struct</span><span class="op"><</span><span class="ident">T</span>, <span class="ident">U</span><span class="op">></span> {
|
||||
<span class="kw">fn</span> <span class="ident">method</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">Self</span><span class="op">></span>) {
|
||||
<span class="kw">let</span> <span class="ident">this</span> <span class="op">=</span> <span class="self">self</span>.<span class="ident">project</span>();
|
||||
<span class="kw">let</span> <span class="kw">_</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">T</span><span class="op">></span> <span class="op">=</span> <span class="ident">this</span>.<span class="ident">pinned</span>; <span class="comment">// Pinned reference to the field</span>
|
||||
<span class="kw">let</span> <span class="kw">_</span>: <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">U</span> <span class="op">=</span> <span class="ident">this</span>.<span class="ident">unpinned</span>; <span class="comment">// Normal reference to the field</span>
|
||||
}
|
||||
}</pre></div>
|
||||
<p>To use <code>pin_project!</code> on enums, you need to name the projection type
|
||||
returned from the method.</p>
|
||||
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">use</span> <span class="ident">pin_project_lite</span>::<span class="ident">pin_project</span>;
|
||||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">pin</span>::<span class="ident">Pin</span>;
|
||||
|
||||
<span class="macro">pin_project</span><span class="macro">!</span> {
|
||||
<span class="attribute">#[<span class="ident">project</span> <span class="op">=</span> <span class="ident">EnumProj</span>]</span>
|
||||
<span class="kw">enum</span> <span class="ident">Enum</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
|
||||
<span class="ident">Struct</span> {
|
||||
<span class="attribute">#[<span class="ident">pin</span>]</span>
|
||||
<span class="ident">field</span>: <span class="ident">T</span>,
|
||||
},
|
||||
<span class="ident">Unit</span>,
|
||||
}
|
||||
}
|
||||
|
||||
<span class="kw">impl</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> <span class="ident">Enum</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
|
||||
<span class="kw">fn</span> <span class="ident">method</span>(<span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">Self</span><span class="op">></span>) {
|
||||
<span class="kw">match</span> <span class="self">self</span>.<span class="ident">project</span>() {
|
||||
<span class="ident">EnumProj</span>::<span class="ident">Struct</span> { <span class="ident">field</span> } <span class="op">=</span><span class="op">></span> {
|
||||
<span class="kw">let</span> <span class="kw">_</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">T</span><span class="op">></span> <span class="op">=</span> <span class="ident">field</span>;
|
||||
}
|
||||
<span class="ident">EnumProj</span>::<span class="ident">Unit</span> <span class="op">=</span><span class="op">></span> {}
|
||||
}
|
||||
}
|
||||
}</pre></div>
|
||||
<p>If you want to call the <code>project()</code> method multiple times or later use the
|
||||
original <a href="https://doc.rust-lang.org/nightly/core/pin/struct.Pin.html"><code>Pin</code></a> type, it needs to use <a href="https://doc.rust-lang.org/nightly/core/pin/struct.Pin.html#method.as_mut"><code>.as_mut()</code></a> to avoid
|
||||
consuming the <a href="https://doc.rust-lang.org/nightly/core/pin/struct.Pin.html"><code>Pin</code></a>.</p>
|
||||
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">use</span> <span class="ident">pin_project_lite</span>::<span class="ident">pin_project</span>;
|
||||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">pin</span>::<span class="ident">Pin</span>;
|
||||
|
||||
<span class="macro">pin_project</span><span class="macro">!</span> {
|
||||
<span class="kw">struct</span> <span class="ident">Struct</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
|
||||
<span class="attribute">#[<span class="ident">pin</span>]</span>
|
||||
<span class="ident">field</span>: <span class="ident">T</span>,
|
||||
}
|
||||
}
|
||||
|
||||
<span class="kw">impl</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> <span class="ident">Struct</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
|
||||
<span class="kw">fn</span> <span class="ident">call_project_twice</span>(<span class="kw-2">mut</span> <span class="self">self</span>: <span class="ident">Pin</span><span class="op"><</span><span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">Self</span><span class="op">></span>) {
|
||||
<span class="comment">// `project` consumes `self`, so reborrow the `Pin<&mut Self>` via `as_mut`.</span>
|
||||
<span class="self">self</span>.<span class="ident">as_mut</span>().<span class="ident">project</span>();
|
||||
<span class="self">self</span>.<span class="ident">as_mut</span>().<span class="ident">project</span>();
|
||||
}
|
||||
}</pre></div>
|
||||
<h1 id="unpin" class="section-header"><a href="#unpin"><code>!Unpin</code></a></h1>
|
||||
<p>If you want to ensure that <a href="https://doc.rust-lang.org/nightly/core/marker/trait.Unpin.html" title="Unpin"><code>Unpin</code></a> is not implemented, use <code>#[pin]</code>
|
||||
attribute for a <a href="https://doc.rust-lang.org/nightly/core/marker/struct.PhantomPinned.html"><code>PhantomPinned</code></a> field.</p>
|
||||
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">use</span> <span class="ident">pin_project_lite</span>::<span class="ident">pin_project</span>;
|
||||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">marker</span>::<span class="ident">PhantomPinned</span>;
|
||||
|
||||
<span class="macro">pin_project</span><span class="macro">!</span> {
|
||||
<span class="kw">struct</span> <span class="ident">Struct</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
|
||||
<span class="ident">field</span>: <span class="ident">T</span>,
|
||||
<span class="attribute">#[<span class="ident">pin</span>]</span> <span class="comment">// <------ This `#[pin]` is required to make `Struct` to `!Unpin`.</span>
|
||||
<span class="ident">_pin</span>: <span class="ident">PhantomPinned</span>,
|
||||
}
|
||||
}</pre></div>
|
||||
<p>Note that using <a href="https://doc.rust-lang.org/nightly/core/marker/struct.PhantomPinned.html"><code>PhantomPinned</code></a> without <code>#[pin]</code> attribute has no effect.</p>
|
||||
</div></section><section id="search" class="content hidden"></section><section class="footer"></section><script>window.rootPath = "../";window.currentCrate = "pin_project_lite";</script><script src="../main.js"></script><script defer src="../search-index.js"></script></body></html>
|
||||
1
doc/pin_project_lite/sidebar-items.js
Normal file
1
doc/pin_project_lite/sidebar-items.js
Normal file
@@ -0,0 +1 @@
|
||||
initSidebarItems({"macro":[["pin_project","A macro that creates a projection type covering all the fields of struct."]]});
|
||||
Reference in New Issue
Block a user