mentat/mio/struct.Registration.html

260 lines
25 KiB
HTML
Raw Permalink Normal View History

2018-08-22 17:04:13 +00:00
<!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 `Registration` struct in crate `mio`.">
<meta name="keywords" content="rust, rustlang, rust-lang, Registration">
<title>mio::Registration - 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="../dark.css">
<link rel="stylesheet" type="text/css" href="../main.css" id="themeStyle">
<script src="../storage.js"></script>
</head>
<body class="rustdoc struct">
<!--[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">&#9776;</div>
<p class='location'>Struct Registration</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#methods">Methods</a><div class="sidebar-links"><a href="#method.new2">new2</a></div><a class="sidebar-title" href="#implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-Send">Send</a><a href="#impl-Sync">Sync</a><a href="#impl-Evented">Evented</a><a href="#impl-Drop">Drop</a><a href="#impl-Debug">Debug</a></div></div><p class='location'><a href='index.html'>mio</a></p><script>window.sidebarCurrent = {name: 'Registration', ty: 'struct', relpath: ''};</script><script defer src="sidebar-items.js"></script></div>
</nav>
<div class="theme-picker">
<button id="theme-picker" aria-label="Pick another theme!">
<img src="../brush.svg" width="18" alt="Pick another theme!">
</button>
<div id="theme-choices"></div>
</div>
<script src="../theme.js"></script>
<nav class="sub">
<form class="search-form js-only">
<div class="search-container">
<input class="search-input" name="search"
autocomplete="off"
placeholder="Click or press S to search, ? for more options…"
type="search">
</div>
</form>
</nav>
<section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Struct <a href='index.html'>mio</a>::<wbr><a class="struct" href=''>Registration</a></span><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'>&#x2212;</span>]
</a>
</span><a class='srclink' href='../src/mio/poll.rs.html#439-441' title='goto source code'>[src]</a></span></h1>
<pre class='rust struct'>pub struct Registration { /* fields omitted */ }</pre><div class='docblock'><p>Handle to a user space <code>Poll</code> registration.</p>
<p><code>Registration</code> allows implementing <a href="event/trait.Evented.html"><code>Evented</code></a> for types that cannot work
with the <a href="struct.Poll.html#implementation-notes">system selector</a>. A <code>Registration</code> is always paired with a
<code>SetReadiness</code>, which allows updating the registration's readiness state.
When <a href="struct.SetReadiness.html#method.set_readiness"><code>set_readiness</code></a> is called and the <code>Registration</code> is associated with a
<a href="struct.Poll.html"><code>Poll</code></a> instance, a readiness event will be created and eventually returned
by <a href="struct.Poll.html"><code>poll</code></a>.</p>
<p>A <code>Registration</code> / <code>SetReadiness</code> pair is created by calling
<a href="struct.Registration.html#method.new2"><code>Registration::new2</code></a>. At this point, the registration is not being
monitored by a <a href="struct.Poll.html"><code>Poll</code></a> instance, so calls to <code>set_readiness</code> will not
result in any readiness notifications.</p>
<p><code>Registration</code> implements <a href="event/trait.Evented.html"><code>Evented</code></a>, so it can be used with <a href="struct.Poll.html"><code>Poll</code></a> using
the same <a href="struct.Poll.html#method.register"><code>register</code></a>, <a href="struct.Poll.html#method.reregister"><code>reregister</code></a>, and <a href="struct.Poll.html#method.deregister"><code>deregister</code></a> functions used
with TCP, UDP, etc... types. Once registered with <a href="struct.Poll.html"><code>Poll</code></a>, readiness state
changes result in readiness events being dispatched to the <a href="struct.Poll.html"><code>Poll</code></a> instance
with which <code>Registration</code> is registered.</p>
<p><strong>Note</strong>, before using <code>Registration</code> be sure to read the
<a href="struct.SetReadiness.html#method.set_readiness"><code>set_readiness</code></a> documentation and the <a href="struct.Poll.html#portability">portability</a> notes. The
guarantees offered by <code>Registration</code> may be weaker than expected.</p>
<p>For high level documentation, see <a href="struct.Poll.html"><code>Poll</code></a>.</p>
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">mio</span>::{<span class="ident">Ready</span>, <span class="ident">Registration</span>, <span class="ident">Poll</span>, <span class="ident">PollOpt</span>, <span class="ident">Token</span>};
<span class="kw">use</span> <span class="ident">mio</span>::<span class="ident">event</span>::<span class="ident">Evented</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">time</span>::<span class="ident">Instant</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">thread</span>;
<span class="kw">pub</span> <span class="kw">struct</span> <span class="ident">Deadline</span> {
<span class="ident">when</span>: <span class="ident">Instant</span>,
<span class="ident">registration</span>: <span class="ident">Registration</span>,
}
<span class="kw">impl</span> <span class="ident">Deadline</span> {
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">new</span>(<span class="ident">when</span>: <span class="ident">Instant</span>) <span class="op">-&gt;</span> <span class="ident">Deadline</span> {
<span class="kw">let</span> (<span class="ident">registration</span>, <span class="ident">set_readiness</span>) <span class="op">=</span> <span class="ident">Registration</span>::<span class="ident">new2</span>();
<span class="ident">thread</span>::<span class="ident">spawn</span>(<span class="kw">move</span> <span class="op">||</span> {
<span class="kw">let</span> <span class="ident">now</span> <span class="op">=</span> <span class="ident">Instant</span>::<span class="ident">now</span>();
<span class="kw">if</span> <span class="ident">now</span> <span class="op">&lt;</span> <span class="ident">when</span> {
<span class="ident">thread</span>::<span class="ident">sleep</span>(<span class="ident">when</span> <span class="op">-</span> <span class="ident">now</span>);
}
<span class="ident">set_readiness</span>.<span class="ident">set_readiness</span>(<span class="ident">Ready</span>::<span class="ident">readable</span>());
});
<span class="ident">Deadline</span> {
<span class="ident">when</span>: <span class="ident">when</span>,
<span class="ident">registration</span>: <span class="ident">registration</span>,
}
}
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">is_elapsed</span>(<span class="kw-2">&amp;</span><span class="self">self</span>) <span class="op">-&gt;</span> <span class="ident">bool</span> {
<span class="ident">Instant</span>::<span class="ident">now</span>() <span class="op">&gt;=</span> <span class="self">self</span>.<span class="ident">when</span>
}
}
<span class="kw">impl</span> <span class="ident">Evented</span> <span class="kw">for</span> <span class="ident">Deadline</span> {
<span class="kw">fn</span> <span class="ident">register</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">poll</span>: <span class="kw-2">&amp;</span><span class="ident">Poll</span>, <span class="ident">token</span>: <span class="ident">Token</span>, <span class="ident">interest</span>: <span class="ident">Ready</span>, <span class="ident">opts</span>: <span class="ident">PollOpt</span>)
<span class="op">-&gt;</span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op">&lt;</span>()<span class="op">&gt;</span>
{
<span class="self">self</span>.<span class="ident">registration</span>.<span class="ident">register</span>(<span class="ident">poll</span>, <span class="ident">token</span>, <span class="ident">interest</span>, <span class="ident">opts</span>)
}
<span class="kw">fn</span> <span class="ident">reregister</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">poll</span>: <span class="kw-2">&amp;</span><span class="ident">Poll</span>, <span class="ident">token</span>: <span class="ident">Token</span>, <span class="ident">interest</span>: <span class="ident">Ready</span>, <span class="ident">opts</span>: <span class="ident">PollOpt</span>)
<span class="op">-&gt;</span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op">&lt;</span>()<span class="op">&gt;</span>
{
<span class="self">self</span>.<span class="ident">registration</span>.<span class="ident">reregister</span>(<span class="ident">poll</span>, <span class="ident">token</span>, <span class="ident">interest</span>, <span class="ident">opts</span>)
}
<span class="kw">fn</span> <span class="ident">deregister</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">poll</span>: <span class="kw-2">&amp;</span><span class="ident">Poll</span>) <span class="op">-&gt;</span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op">&lt;</span>()<span class="op">&gt;</span> {
<span class="self">self</span>.<span class="ident">registration</span>.<span class="ident">deregister</span>(<span class="ident">poll</span>)
}
}</pre>
</div>
<h2 id='methods' class='small-section-header'>
Methods<a href='#methods' class='anchor'></a>
</h2>
<h3 id='impl' class='impl'><span class='in-band'><code>impl <a class="struct" href="../mio/struct.Registration.html" title="struct mio::Registration">Registration</a></code><a href='#impl' class='anchor'></a></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1538-1663' title='goto source code'>[src]</a></span></h3>
<div class='impl-items'><h4 id='method.new2' class="method"><span id='new2.v' class='invisible'><code>pub fn <a href='#method.new2' class='fnname'>new2</a>() -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">(</a><a class="struct" href="../mio/struct.Registration.html" title="struct mio::Registration">Registration</a>, <a class="struct" href="../mio/struct.SetReadiness.html" title="struct mio::SetReadiness">SetReadiness</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">)</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1585-1604' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Create and return a new <code>Registration</code> and the associated
<code>SetReadiness</code>.</p>
<p>See <a href="#">struct</a> documentation for more detail and <a href="struct.Poll.html"><code>Poll</code></a>
for high level documentation on polling.</p>
<h1 id="examples-1" class="section-header"><a href="#examples-1">Examples</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">mio</span>::{<span class="ident">Events</span>, <span class="ident">Ready</span>, <span class="ident">Registration</span>, <span class="ident">Poll</span>, <span class="ident">PollOpt</span>, <span class="ident">Token</span>};
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">thread</span>;
<span class="kw">let</span> (<span class="ident">registration</span>, <span class="ident">set_readiness</span>) <span class="op">=</span> <span class="ident">Registration</span>::<span class="ident">new2</span>();
<span class="ident">thread</span>::<span class="ident">spawn</span>(<span class="kw">move</span> <span class="op">||</span> {
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">time</span>::<span class="ident">Duration</span>;
<span class="ident">thread</span>::<span class="ident">sleep</span>(<span class="ident">Duration</span>::<span class="ident">from_millis</span>(<span class="number">500</span>));
<span class="ident">set_readiness</span>.<span class="ident">set_readiness</span>(<span class="ident">Ready</span>::<span class="ident">readable</span>());
});
<span class="kw">let</span> <span class="ident">poll</span> <span class="op">=</span> <span class="ident">Poll</span>::<span class="ident">new</span>()<span class="question-mark">?</span>;
<span class="ident">poll</span>.<span class="ident">register</span>(<span class="kw-2">&amp;</span><span class="ident">registration</span>, <span class="ident">Token</span>(<span class="number">0</span>), <span class="ident">Ready</span>::<span class="ident">readable</span>() <span class="op">|</span> <span class="ident">Ready</span>::<span class="ident">writable</span>(), <span class="ident">PollOpt</span>::<span class="ident">edge</span>())<span class="question-mark">?</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">events</span> <span class="op">=</span> <span class="ident">Events</span>::<span class="ident">with_capacity</span>(<span class="number">256</span>);
<span class="kw">loop</span> {
<span class="ident">poll</span>.<span class="ident">poll</span>(<span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">events</span>, <span class="prelude-val">None</span>);
<span class="kw">for</span> <span class="ident">event</span> <span class="kw">in</span> <span class="kw-2">&amp;</span><span class="ident">events</span> {
<span class="kw">if</span> <span class="ident">event</span>.<span class="ident">token</span>() <span class="op">==</span> <span class="ident">Token</span>(<span class="number">0</span>) <span class="op">&amp;&amp;</span> <span class="ident">event</span>.<span class="ident">readiness</span>().<span class="ident">is_readable</span>() {
<span class="kw">return</span> <span class="prelude-val">Ok</span>(());
}
}
}</pre>
</div></div>
<h2 id='implementations' class='small-section-header'>
Trait Implementations<a href='#implementations' class='anchor'></a>
</h2>
<h3 id='impl-Send' class='impl'><span class='in-band'><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Send.html" title="trait core::marker::Send">Send</a> for <a class="struct" href="../mio/struct.Registration.html" title="struct mio::Registration">Registration</a></code><a href='#impl-Send' class='anchor'></a></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#443' title='goto source code'>[src]</a></span></h3>
<div class='impl-items'></div><h3 id='impl-Sync' class='impl'><span class='in-band'><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sync.html" title="trait core::marker::Sync">Sync</a> for <a class="struct" href="../mio/struct.Registration.html" title="struct mio::Registration">Registration</a></code><a href='#impl-Sync' class='anchor'></a></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#444' title='goto source code'>[src]</a></span></h3>
<div class='impl-items'></div><h3 id='impl-Evented' class='impl'><span class='in-band'><code>impl <a class="trait" href="../mio/event/trait.Evented.html" title="trait mio::event::Evented">Evented</a> for <a class="struct" href="../mio/struct.Registration.html" title="struct mio::Registration">Registration</a></code><a href='#impl-Evented' class='anchor'></a></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1665-1677' title='goto source code'>[src]</a></span></h3>
<div class='impl-items'><h4 id='method.register' class="method"><span id='register.v' class='invisible'><code>fn <a href='../mio/event/trait.Evented.html#tymethod.register' class='fnname'>register</a>(<br>&nbsp;&nbsp;&nbsp;&nbsp;&amp;self, <br>&nbsp;&nbsp;&nbsp;&nbsp;poll: &amp;<a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;token: <a class="struct" href="../mio/struct.Token.html" title="struct mio::Token">Token</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;interest: <a class="struct" href="../mio/struct.Ready.html" title="struct mio::Ready">Ready</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;opts: <a class="struct" href="../mio/struct.PollOpt.html" title="struct mio::PollOpt">PollOpt</a><br>) -&gt; <a class="type" href="https://doc.rust-lang.org/nightly/std/io/error/type.Result.html" title="type std::io::error::Result">Result</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1666-1668' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Register <code>self</code> with the given <code>Poll</code> instance. <a href="../mio/event/trait.Evented.html#tymethod.register">Read more</a></p>
</div><h4 id='method.reregister' class="method"><span id='reregister.v' class='invisible'><code>fn <a href='../mio/event/trait.Evented.html#tymethod.reregister' class='fnname'>reregister</a>(<br>&nbsp;&nbsp;&nbsp;&nbsp;&amp;self, <br>&nbsp;&nbsp;&nbsp;&nbsp;poll: &amp;<a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;token: <a class="struct" href="../mio/struct.Token.html" title="struct mio::Token">Token</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;interest: <a class="struct" href="../mio/struct.Ready.html" title="struct mio::Ready">Ready</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;opts: <a class="struct" href="../mio/struct.PollOpt.html" title="struct mio::PollOpt">PollOpt</a><br>) -&gt; <a class="type" href="https://doc.rust-lang.org/nightly/std/io/error/type.Result.html" title="type std::io::error::Result">Result</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1670-1672' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Re-register <code>self</code> with the given <code>Poll</code> instance. <a href="../mio/event/trait.Evented.html#tymethod.reregister">Read more</a></p>
</div><h4 id='method.deregister' class="method"><span id='deregister.v' class='invisible'><code>fn <a href='../mio/event/trait.Evented.html#tymethod.deregister' class='fnname'>deregister</a>(&amp;self, poll: &amp;<a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a>) -&gt; <a class="type" href="https://doc.rust-lang.org/nightly/std/io/error/type.Result.html" title="type std::io::error::Result">Result</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>&gt;</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1674-1676' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Deregister <code>self</code> from the given <code>Poll</code> instance <a href="../mio/event/trait.Evented.html#tymethod.deregister">Read more</a></p>
</div></div><h3 id='impl-Drop' class='impl'><span class='in-band'><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/ops/drop/trait.Drop.html" title="trait core::ops::drop::Drop">Drop</a> for <a class="struct" href="../mio/struct.Registration.html" title="struct mio::Registration">Registration</a></code><a href='#impl-Drop' class='anchor'></a></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1679-1689' title='goto source code'>[src]</a></span></h3>
<div class='impl-items'><h4 id='method.drop' class="method"><span id='drop.v' class='invisible'><code>fn <a href='https://doc.rust-lang.org/nightly/core/ops/drop/trait.Drop.html#tymethod.drop' class='fnname'>drop</a>(&amp;mut self)</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1680-1688' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Executes the destructor for this type. <a href="https://doc.rust-lang.org/nightly/core/ops/drop/trait.Drop.html#tymethod.drop">Read more</a></p>
</div></div><h3 id='impl-Debug' class='impl'><span class='in-band'><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a> for <a class="struct" href="../mio/struct.Registration.html" title="struct mio::Registration">Registration</a></code><a href='#impl-Debug' class='anchor'></a></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1691-1696' title='goto source code'>[src]</a></span></h3>
<div class='impl-items'><h4 id='method.fmt' class="method"><span id='fmt.v' class='invisible'><code>fn <a href='https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html#tymethod.fmt' class='fnname'>fmt</a>(&amp;self, fmt: &amp;mut <a class="struct" href="https://doc.rust-lang.org/nightly/core/fmt/struct.Formatter.html" title="struct core::fmt::Formatter">Formatter</a>) -&gt; <a class="type" href="https://doc.rust-lang.org/nightly/core/fmt/type.Result.html" title="type core::fmt::Result">Result</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1692-1695' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Formats the value using the given formatter. <a href="https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html#tymethod.fmt">Read more</a></p>
</div></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>&#9166;</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>
</div>
</div>
</aside>
<script>
window.rootPath = "../";
window.currentCrate = "mio";
</script>
<script src="../main.js"></script>
<script defer src="../search-index.js"></script>
</body>
</html>