KA-DEVS/mcquery-rs
5
0
Fork 0
Code Issues Pull Requests Releases Activity
b89c52748d
mcquery-rs/doc/mio/struct.Poll.html

248 lines
44 KiB
HTML
Raw Normal View History

Add generated documentation
2021-01-08 20:01:01 +01: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 `Poll` struct in crate `mio`."><meta name="keywords" content="rust, rustlang, rust-lang, Poll"><title>mio::Poll - 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 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><a href='../mio/index.html'><div class='logo-container rust-logo'><img src='../rust-logo.png' alt='logo'></div></a><p class="location">Struct Poll</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#implementations">Methods</a><div class="sidebar-links"><a href="#method.new">new</a><a href="#method.poll">poll</a><a href="#method.registry">registry</a></div><a class="sidebar-title" href="#trait-implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-AsRawFd">AsRawFd</a><a href="#impl-Debug">Debug</a></div><a class="sidebar-title" href="#synthetic-implementations">Auto Trait Implementations</a><div class="sidebar-links"><a href="#impl-RefUnwindSafe">RefUnwindSafe</a><a href="#impl-Send">Send</a><a href="#impl-Sync">Sync</a><a href="#impl-Unpin">Unpin</a><a href="#impl-UnwindSafe">UnwindSafe</a></div><a class="sidebar-title" href="#blanket-implementations">Blanket Implementations</a><div class="sidebar-links"><a href="#impl-Any">Any</a><a href="#impl-Borrow%3CT%3E">Borrow&lt;T&gt;</a><a href="#impl-BorrowMut%3CT%3E">BorrowMut&lt;T&gt;</a><a href="#impl-From%3CT%3E">From&lt;T&gt;</a><a href="#impl-Into%3CU%3E">Into&lt;U&gt;</a><a href="#impl-TryFrom%3CU%3E">TryFrom&lt;U&gt;</a><a href="#impl-TryInto%3CU%3E">TryInto&lt;U&gt;</a></div></div><p class="location"><a href="index.html">mio</a></p><script>window.sidebarCurrent = {name: "Poll", 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!" 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">&#x2212;</span>]</a></span><a class="srclink" href="../src/mio/poll.rs.html#204-206" title="goto source code">[src]</a></span><span class="in-band">Struct <a href="index.html">mio</a>::<wbr><a class="struct" href="">Poll</a></span></h1><div class="docblock type-decl hidden-by-usual-hider"><pre class="rust struct">pub struct Poll { /* fields omitted */ }</pre></div><div class="docblock"><p>Polls for readiness events on all registered values.</p>
<p><code>Poll</code> allows a program to monitor a large number of <a href="./event/trait.Source.html"><code>event::Source</code></a>s,
waiting until one or more become &quot;ready&quot; for some class of operations; e.g.
reading and writing. An event source is considered ready if it is possible
to immediately perform a corresponding operation; e.g. <a href="./net/struct.TcpStream.html#method.read"><code>read</code></a> or
<a href="./net/struct.TcpStream.html#method.write"><code>write</code></a>.</p>
<p>To use <code>Poll</code>, an <code>event::Source</code> must first be registered with the <code>Poll</code>
instance using the <a href="struct.Registry.html#method.register"><code>register</code></a> method on its associated <code>Register</code>,
supplying readiness interest. The readiness interest tells <code>Poll</code> which
specific operations on the handle to monitor for readiness. A <code>Token</code> is
also passed to the <a href="struct.Registry.html#method.register"><code>register</code></a> function. When <code>Poll</code> returns a readiness
event, it will include this token. This associates the event with the
event source that generated the event.</p>
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
<p>A basic example -- establishing a <code>TcpStream</code> connection.</p>
<div class='information'><div class='tooltip ignore'>ⓘ<span class='tooltiptext'>This example is not tested</span></div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore">
<span class="kw">use</span> <span class="ident">mio</span>::{<span class="ident">Events</span>, <span class="ident">Poll</span>, <span class="ident">Interest</span>, <span class="ident">Token</span>};
<span class="kw">use</span> <span class="ident">mio</span>::<span class="ident">net</span>::<span class="ident">TcpStream</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">net</span>::{<span class="self">self</span>, <span class="ident">SocketAddr</span>};
<span class="comment">// Bind a server socket to connect to.</span>
<span class="kw">let</span> <span class="ident">addr</span>: <span class="ident">SocketAddr</span> <span class="op">=</span> <span class="string">&quot;127.0.0.1:0&quot;</span>.<span class="ident">parse</span>()<span class="question-mark">?</span>;
<span class="kw">let</span> <span class="ident">server</span> <span class="op">=</span> <span class="ident">net</span>::<span class="ident">TcpListener</span>::<span class="ident">bind</span>(<span class="ident">addr</span>)<span class="question-mark">?</span>;
<span class="comment">// Construct a new `Poll` handle as well as the `Events` we&#39;ll store into</span>
<span class="kw">let</span> <span class="kw-2">mut</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="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">1024</span>);
<span class="comment">// Connect the stream</span>
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream</span> <span class="op">=</span> <span class="ident">TcpStream</span>::<span class="ident">connect</span>(<span class="ident">server</span>.<span class="ident">local_addr</span>()<span class="question-mark">?</span>)<span class="question-mark">?</span>;
<span class="comment">// Register the stream with `Poll`</span>
<span class="ident">poll</span>.<span class="ident">registry</span>().<span class="ident">register</span>(<span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">stream</span>, <span class="ident">Token</span>(<span class="number">0</span>), <span class="ident">Interest</span>::<span class="ident">READABLE</span> <span class="op">|</span> <span class="ident">Interest</span>::<span class="ident">WRITABLE</span>)<span class="question-mark">?</span>;
<span class="comment">// Wait for the socket to become ready. This has to happens in a loop to</span>
<span class="comment">// handle spurious wakeups.</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="question-mark">?</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="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">is_writable</span>() {
<span class="comment">// The socket connected (probably, it could still be a spurious</span>
<span class="comment">// wakeup)</span>
<span class="kw">return</span> <span class="prelude-val">Ok</span>(());
}
}
}</pre></div>
<h1 id="portability" class="section-header"><a href="#portability">Portability</a></h1>
<p>Using <code>Poll</code> provides a portable interface across supported platforms as
long as the caller takes the following into consideration:</p>
<h3 id="spurious-events" class="section-header"><a href="#spurious-events">Spurious events</a></h3>
<p><a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> may return readiness events even if the associated
event source is not actually ready. Given the same code, this may
happen more on some platforms than others. It is important to never assume
that, just because a readiness event was received, that the associated
operation will succeed as well.</p>
<p>If operation fails with <a href="https://doc.rust-lang.org/nightly/std/io/error/enum.ErrorKind.html#variant.WouldBlock"><code>WouldBlock</code></a>, then the caller should not treat
this as an error, but instead should wait until another readiness event is
received.</p>
<h3 id="draining-readiness" class="section-header"><a href="#draining-readiness">Draining readiness</a></h3>
<p>Once a readiness event is received, the corresponding operation must be
performed repeatedly until it returns <a href="https://doc.rust-lang.org/nightly/std/io/error/enum.ErrorKind.html#variant.WouldBlock"><code>WouldBlock</code></a>. Unless this is done,
there is no guarantee that another readiness event will be delivered, even
if further data is received for the event source.</p>
<h3 id="readiness-operations" class="section-header"><a href="#readiness-operations">Readiness operations</a></h3>
<p>The only readiness operations that are guaranteed to be present on all
supported platforms are <a href="./event/struct.Event.html#method.is_readable"><code>readable</code></a> and <a href="./event/struct.Event.html#method.is_writable"><code>writable</code></a>. All other readiness
operations may have false negatives and as such should be considered
<strong>hints</strong>. This means that if a socket is registered with <a href="./event/struct.Event.html#method.is_readable"><code>readable</code></a>
interest and either an error or close is received, a readiness event will
be generated for the socket, but it <strong>may</strong> only include <code>readable</code>
readiness. Also note that, given the potential for spurious events,
receiving a readiness event with <code>read_closed</code>, <code>write_closed</code>, or <code>error</code>
doesn't actually mean that a <code>read</code> on the socket will return a result
matching the readiness event.</p>
<p>In other words, portable programs that explicitly check for <a href="./event/struct.Event.html#method.is_read_closed"><code>read_closed</code></a>,
<a href="./event/struct.Event.html#method.is_write_closed"><code>write_closed</code></a>, or <a href="./event/struct.Event.html#method.is_error"><code>error</code></a> readiness should be doing so as an
<strong>optimization</strong> and always be able to handle an error or close situation
when performing the actual read operation.</p>
<h3 id="registering-handles" class="section-header"><a href="#registering-handles">Registering handles</a></h3>
<p>Unless otherwise noted, it should be assumed that types implementing
<a href="./event/trait.Source.html"><code>event::Source</code></a> will never become ready unless they are registered with
<code>Poll</code>.</p>
<p>For example:</p>
<div class='information'><div class='tooltip ignore'>ⓘ<span class='tooltiptext'>This example is not tested</span></div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore">
<span class="kw">use</span> <span class="ident">mio</span>::{<span class="ident">Poll</span>, <span class="ident">Interest</span>, <span class="ident">Token</span>};
<span class="kw">use</span> <span class="ident">mio</span>::<span class="ident">net</span>::<span class="ident">TcpStream</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">net</span>::<span class="ident">SocketAddr</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">time</span>::<span class="ident">Duration</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">thread</span>;
<span class="kw">let</span> <span class="ident">address</span>: <span class="ident">SocketAddr</span> <span class="op">=</span> <span class="string">&quot;127.0.0.1:0&quot;</span>.<span class="ident">parse</span>()<span class="question-mark">?</span>;
<span class="kw">let</span> <span class="ident">listener</span> <span class="op">=</span> <span class="ident">net</span>::<span class="ident">TcpListener</span>::<span class="ident">bind</span>(<span class="ident">address</span>)<span class="question-mark">?</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">sock</span> <span class="op">=</span> <span class="ident">TcpStream</span>::<span class="ident">connect</span>(<span class="ident">listener</span>.<span class="ident">local_addr</span>()<span class="question-mark">?</span>)<span class="question-mark">?</span>;
<span class="ident">thread</span>::<span class="ident">sleep</span>(<span class="ident">Duration</span>::<span class="ident">from_secs</span>(<span class="number">1</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="comment">// The connect is not guaranteed to have started until it is registered at</span>
<span class="comment">// this point</span>
<span class="ident">poll</span>.<span class="ident">registry</span>().<span class="ident">register</span>(<span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">sock</span>, <span class="ident">Token</span>(<span class="number">0</span>), <span class="ident">Interest</span>::<span class="ident">READABLE</span> <span class="op">|</span> <span class="ident">Interest</span>::<span class="ident">WRITABLE</span>)<span class="question-mark">?</span>;</pre></div>
<h3 id="dropping-poll" class="section-header"><a href="#dropping-poll">Dropping <code>Poll</code></a></h3>
<p>When the <code>Poll</code> instance is dropped it may cancel in-flight operations for
the registered <a href="./event/trait.Source.html">event sources</a>, meaning that no further events for them may
be received. It also means operations on the registered event sources may no
longer work. It is up to the user to keep the <code>Poll</code> instance alive while
registered event sources are being used.</p>
<h1 id="implementation-notes" class="section-header"><a href="#implementation-notes">Implementation notes</a></h1>
<p><code>Poll</code> is backed by the selector provided by the operating system.</p>
<table><thead><tr><th>OS</th><th>Selector</th></tr></thead><tbody>
<tr><td>Android</td><td><a href="http://man7.org/linux/man-pages/man7/epoll.7.html">epoll</a></td></tr>
<tr><td>DragonFly BSD</td><td><a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&amp;sektion=2">kqueue</a></td></tr>
<tr><td>FreeBSD</td><td><a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&amp;sektion=2">kqueue</a></td></tr>
<tr><td>Linux</td><td><a href="http://man7.org/linux/man-pages/man7/epoll.7.html">epoll</a></td></tr>
<tr><td>NetBSD</td><td><a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&amp;sektion=2">kqueue</a></td></tr>
<tr><td>OpenBSD</td><td><a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&amp;sektion=2">kqueue</a></td></tr>
<tr><td>Solaris</td><td><a href="http://man7.org/linux/man-pages/man7/epoll.7.html">epoll</a></td></tr>
<tr><td>illumos</td><td><a href="http://man7.org/linux/man-pages/man7/epoll.7.html">epoll</a></td></tr>
<tr><td>Windows</td><td><a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365198(v=vs.85).aspx">IOCP</a></td></tr>
<tr><td>iOS</td><td><a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&amp;sektion=2">kqueue</a></td></tr>
<tr><td>macOS</td><td><a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&amp;sektion=2">kqueue</a></td></tr>
</tbody></table>
<p>On all supported platforms, socket operations are handled by using the
system selector. Platform specific extensions (e.g. <a href="unix/struct.SourceFd.html"><code>SourceFd</code></a>) allow
accessing other features provided by individual system selectors. For
example, Linux's <a href="http://man7.org/linux/man-pages/man2/signalfd.2.html"><code>signalfd</code></a> feature can be used by registering the FD with
<code>Poll</code> via <a href="unix/struct.SourceFd.html"><code>SourceFd</code></a>.</p>
<p>On all platforms except windows, a call to <a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> is mostly just a
direct call to the system selector. However, <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365198(v=vs.85).aspx">IOCP</a> uses a completion model
instead of a readiness model. In this case, <code>Poll</code> must adapt the completion
model Mio's API. While non-trivial, the bridge layer is still quite
efficient. The most expensive part being calls to <code>read</code> and <code>write</code> require
data to be copied into an intermediate buffer before it is passed to the
kernel.</p>
</div><h2 id="implementations" class="small-section-header">Implementations<a href="#implementations" class="anchor"></a></h2><h3 id="impl" class="impl"><code class="in-band">impl <a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a></code><a href="#impl" class="anchor"></a><a class="srclink" href="../src/mio/poll.rs.html#213-316" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.registry" class="method"><code>pub fn <a href="#method.registry" class="fnname">registry</a>(&amp;self) -&gt; &amp;<a class="struct" href="../mio/struct.Registry.html" title="struct mio::Registry">Registry</a></code><a class="srclink" href="../src/mio/poll.rs.html#216-218" title="goto source code">[src]</a></h4><div class="docblock"><p>Create a separate <code>Registry</code> which can be used to register
<code>event::Source</code>s.</p>
</div><h4 id="method.poll" class="method"><code>pub fn <a href="#method.poll" class="fnname">poll</a>(<br>&nbsp;&nbsp;&nbsp;&nbsp;&amp;mut self, <br>&nbsp;&nbsp;&nbsp;&nbsp;events: &amp;mut <a class="struct" href="../mio/event/struct.Events.html" title="struct mio::event::Events">Events</a>, <br>&nbsp;&nbsp;&nbsp;&nbsp;timeout: <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="struct" href="https://doc.rust-lang.org/nightly/core/time/struct.Duration.html" title="struct core::time::Duration">Duration</a>&gt;<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><a class="srclink" href="../src/mio/poll.rs.html#313-315" title="goto source code">[src]</a></h4><div class="docblock"><p>Wait for readiness events</p>
<p>Blocks the current thread and waits for readiness events for any of the
<a href="./event/trait.Source.html"><code>event::Source</code></a>s that have been registered with this <code>Poll</code> instance.
The function will block until either at least one readiness event has
been received or <code>timeout</code> has elapsed. A <code>timeout</code> of <code>None</code> means that
<code>poll</code> will block until a readiness event has been received.</p>
<p>The supplied <code>events</code> will be cleared and newly received readiness events
will be pushed onto the end. At most <code>events.capacity()</code> events will be
returned. If there are further pending readiness events, they will be
returned on the next call to <code>poll</code>.</p>
<p>A single call to <code>poll</code> may result in multiple readiness events being
returned for a single event source. For example, if a TCP socket becomes
both readable and writable, it may be possible for a single readiness
event to be returned with both <a href="struct.Interest.html#associatedconstant.READABLE"><code>readable</code></a> and <a href="struct.Interest.html#associatedconstant.WRITABLE"><code>writable</code></a> readiness
<strong>OR</strong> two separate events may be returned, one with <a href="struct.Interest.html#associatedconstant.READABLE"><code>readable</code></a> set
and one with <a href="struct.Interest.html#associatedconstant.WRITABLE"><code>writable</code></a> set.</p>
<p>Note that the <code>timeout</code> will be rounded up to the system clock
granularity (usually 1ms), and kernel scheduling delays mean that
the blocking interval may be overrun by a small amount.</p>
<p>See the <a href="struct.Poll.html">struct</a> level documentation for a higher level discussion of
polling.</p>
<h1 id="notes" class="section-header"><a href="#notes">Notes</a></h1>
<p>This returns any errors without attempting to retry, previous versions
of Mio would automatically retry the poll call if it was interrupted
(if <code>EINTR</code> was returned).</p>
<h1 id="examples-1" class="section-header"><a href="#examples-1">Examples</a></h1>
<p>A basic example -- establishing a <code>TcpStream</code> connection.</p>
<div class='information'><div class='tooltip ignore'>ⓘ<span class='tooltiptext'>This example is not tested</span></div></div><div class="example-wrap"><pre class="rust rust-example-rendered ignore">
<span class="kw">use</span> <span class="ident">mio</span>::{<span class="ident">Events</span>, <span class="ident">Poll</span>, <span class="ident">Interest</span>, <span class="ident">Token</span>};
<span class="kw">use</span> <span class="ident">mio</span>::<span class="ident">net</span>::<span class="ident">TcpStream</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">net</span>::{<span class="ident">TcpListener</span>, <span class="ident">SocketAddr</span>};
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">thread</span>;
<span class="comment">// Bind a server socket to connect to.</span>
<span class="kw">let</span> <span class="ident">addr</span>: <span class="ident">SocketAddr</span> <span class="op">=</span> <span class="string">&quot;127.0.0.1:0&quot;</span>.<span class="ident">parse</span>()<span class="question-mark">?</span>;
<span class="kw">let</span> <span class="ident">server</span> <span class="op">=</span> <span class="ident">TcpListener</span>::<span class="ident">bind</span>(<span class="ident">addr</span>)<span class="question-mark">?</span>;
<span class="kw">let</span> <span class="ident">addr</span> <span class="op">=</span> <span class="ident">server</span>.<span class="ident">local_addr</span>()<span class="question-mark">?</span>.<span class="ident">clone</span>();
<span class="comment">// Spawn a thread to accept the socket</span>
<span class="ident">thread</span>::<span class="ident">spawn</span>(<span class="kw">move</span> <span class="op">|</span><span class="op">|</span> {
<span class="kw">let</span> <span class="kw">_</span> <span class="op">=</span> <span class="ident">server</span>.<span class="ident">accept</span>();
});
<span class="comment">// Construct a new `Poll` handle as well as the `Events` we&#39;ll store into</span>
<span class="kw">let</span> <span class="kw-2">mut</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="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">1024</span>);
<span class="comment">// Connect the stream</span>
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream</span> <span class="op">=</span> <span class="ident">TcpStream</span>::<span class="ident">connect</span>(<span class="ident">addr</span>)<span class="question-mark">?</span>;
<span class="comment">// Register the stream with `Poll`</span>
<span class="ident">poll</span>.<span class="ident">registry</span>().<span class="ident">register</span>(
<span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">stream</span>,
<span class="ident">Token</span>(<span class="number">0</span>),
<span class="ident">Interest</span>::<span class="ident">READABLE</span> <span class="op">|</span> <span class="ident">Interest</span>::<span class="ident">WRITABLE</span>)<span class="question-mark">?</span>;
<span class="comment">// Wait for the socket to become ready. This has to happens in a loop to</span>
<span class="comment">// handle spurious wakeups.</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="question-mark">?</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="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">is_writable</span>() {
<span class="comment">// The socket connected (probably, it could still be a spurious</span>
<span class="comment">// wakeup)</span>
<span class="kw">return</span> <span class="prelude-val">Ok</span>(());
}
}
}</pre></div>
</div></div><h3 id="impl-1" class="impl"><code class="in-band">impl <a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a></code><a href="#impl-1" class="anchor"></a><a class="srclink" href="../src/mio/poll.rs.html#319-358" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.new" class="method"><code>pub fn <a href="#method.new" class="fnname">new</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="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a>&gt;</code><a class="srclink" href="../src/mio/poll.rs.html#353-357" title="goto source code">[src]</a></h4><div class="docblock"><p>Return a new <code>Poll</code> handle.</p>
<p>This function will make a syscall to the operating system to create
the system selector. If this syscall fails, <code>Poll::new</code> will return
with the error.</p>
<p>See <a href="struct.Poll.html">struct</a> level docs for more details.</p>
<h1 id="examples-2" class="section-header"><a href="#examples-2">Examples</a></h1>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">mio</span>::{<span class="ident">Poll</span>, <span class="ident">Events</span>};
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">time</span>::<span class="ident">Duration</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">poll</span> <span class="op">=</span> <span class="kw">match</span> <span class="ident">Poll</span>::<span class="ident">new</span>() {
<span class="prelude-val">Ok</span>(<span class="ident">poll</span>) <span class="op">=</span><span class="op">&gt;</span> <span class="ident">poll</span>,
<span class="prelude-val">Err</span>(<span class="ident">e</span>) <span class="op">=</span><span class="op">&gt;</span> <span class="macro">panic</span><span class="macro">!</span>(<span class="string">&quot;failed to create Poll instance; err={:?}&quot;</span>, <span class="ident">e</span>),
};
<span class="comment">// Create a structure to receive polled events</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">1024</span>);
<span class="comment">// Wait for events, but none will be received because no</span>
<span class="comment">// `event::Source`s have been registered with this `Poll` instance.</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">Some</span>(<span class="ident">Duration</span>::<span class="ident">from_millis</span>(<span class="number">500</span>)))<span class="question-mark">?</span>;
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">events</span>.<span class="ident">is_empty</span>());</pre></div>
</div></div><h2 id="trait-implementations" class="small-section-header">Trait Implementations<a href="#trait-implementations" class="anchor"></a></h2><div id="trait-implementations-list"><h3 id="impl-AsRawFd" class="impl"><code class="in-band">impl <a class="trait" href="https://doc.rust-lang.org/nightly/std/sys/unix/ext/io/trait.AsRawFd.html" title="trait std::sys::unix::ext::io::AsRawFd">AsRawFd</a> for <a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a></code><a href="#impl-AsRawFd" class="anchor"></a><a class="srclink" href="../src/mio/poll.rs.html#362-366" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.as_raw_fd" class="method hidden"><code>fn <a href="https://doc.rust-lang.org/nightly/std/sys/unix/ext/io/trait.AsRawFd.html#tymethod.as_raw_fd" class="fnname">as_raw_fd</a>(&amp;self) -&gt; <a class="type" href="https://doc.rust-lang.org/nightly/std/sys/unix/ext/io/type.RawFd.html" title="type std::sys::unix::ext::io::RawFd">RawFd</a></code><a class="srclink" href="../src/mio/poll.rs.html#363-365" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Extracts the raw file descriptor. <a href="https://doc.rust-lang.org/nightly/std/sys/unix/ext/io/trait.AsRawFd.html#tymethod.as_raw_fd">Read more</a></p>
</div></div><h3 id="impl-Debug" class="impl"><code class="in-band">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.Poll.html" title="struct mio::Poll">Poll</a></code><a href="#impl-Debug" class="anchor"></a><a class="srclink" href="../src/mio/poll.rs.html#368-372" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.fmt" class="method hidden"><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>&lt;'_&gt;) -&gt; <a class="type" href="https://doc.rust-lang.org/nightly/core/fmt/type.Result.html" title="type core::fmt::Result">Result</a></code><a class="srclink" href="../src/mio/poll.rs.html#369-371" title="goto source code">[src]</a></h4><div class='docblock hidden'><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></div><h2 id="synthetic-implementations" class="small-section-header">Auto Trait Implementations<a href="#synthetic-implementations" class="anchor"></a></h2><div id="synthetic-implementations-list"><h3 id="impl-RefUnwindSafe" class="impl"><code class="in-band">impl <a class="trait" href="https://doc.rust-lang.org/nightly/std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> for <a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a></code><a href="#impl-RefUnwindSafe" class="anchor"></a></h3><div class="impl-items"></div><h3 id="impl-Send" class="impl"><code class="in-band">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.Poll.html" title="struct mio::Poll">Poll</a></code><a href="#impl-Send" class="anchor"></a></h3><div class="impl-items"></div><h3 id="impl-Sync" class="impl"><code class="in-band">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.Poll.html" title="struct mio::Poll">Poll</a></code><a href="#impl-Sync" class="anchor"></a></h3><div class="impl-items"></div><h3 id="impl-Unpin" class="impl"><code class="in-band">impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a> for <a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a></code><a href="#impl-Unpin" class="anchor"></a></h3><div class="impl-items"></div><h3 id="impl-UnwindSafe" class="impl"><code class="in-band">impl <a class="trait" href="https://doc.rust-lang.org/nightly/std/panic/trait.UnwindSafe.html" title="trait std::panic::UnwindSafe">UnwindSafe</a> for <a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a></code><a href="#impl-UnwindSafe" class="anchor"></a></h3><div class="impl-items"></div></div><h2 id="blanket-implementations" class="small-section-header">Blanket Implementations<a href="#blanket-implementations" class="anchor"></a></h2><div id="blanket-implementations-list"><h3 id="impl-Any" class="impl"><code class="in-band">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/nightly/core/any/trait.Any.html" title="trait core::any::Any">Any</a> for T <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;T: 'static + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,&nbsp;</span></code><a href="#impl-Any" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/any.rs.html#108-112" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.type_id" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/any/trait.Any.html#tymethod.type_id" class="fnname">type_id</a>(&amp;self) -&gt; <a class="struct" href="https://doc.rust-lang.org/nightly/core/any/struct.TypeId.html" title="struct core::any::TypeId">TypeId</a></code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/any.rs.html#109-111" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Gets the <code>TypeId</code> of <code>self</code>. <a href="https://doc.rust-lang.org/nightly/core/any/trait.Any.html#tymethod.type_id">Read more</a></p>
</div></div><h3 id="impl-Borrow%3CT%3E" class="impl"><code class="in-band">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html" title="trait core::borrow::Borrow">Borrow</a>&lt;T&gt; for T <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;T: ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,&nbsp;</span></code><a href="#impl-Borrow%3CT%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#210-214" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.borrow" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html#tymethod.borrow" class="fnname">borrow</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&amp;</a>T</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#211-213" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Immutably borrows from an owned value. <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html#tymethod.borrow">Read more</a></p>
</div></div><h3 id="impl-BorrowMut%3CT%3E" class="impl"><code class="in-band">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/nightly/core/borrow/trait.BorrowMut.html" title="trait core::borrow::BorrowMut">BorrowMut</a>&lt;T&gt; for T <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;T: ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,&nbsp;</span></code><a href="#impl-BorrowMut%3CT%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#217-221" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.borrow_mut" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.BorrowMut.html#tymethod.borrow_mut" class="fnname">borrow_mut</a>(&amp;mut self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&amp;mut </a>T</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#218-220" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Mutably borrows from an owned value. <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.BorrowMut.html#tymethod.borrow_mut">Read more</a></p>
</div></div><h3 id="impl-From%3CT%3E" class="impl"><code class="in-band">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html" title="trait core::convert::From">From</a>&lt;T&gt; for T</code><a href="#impl-From%3CT%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#552-556" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.from" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html#tymethod.from" class="fnname">from</a>(t: T) -&gt; T</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#553-555" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
</div></div><h3 id="impl-Into%3CU%3E" class="impl"><code class="in-band">impl&lt;T, U&gt; <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;U&gt; for T <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;U: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html" title="trait core::convert::From">From</a>&lt;T&gt;,&nbsp;</span></code><a href="#impl-Into%3CU%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#541-548" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.into" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html#tymethod.into" class="fnname">into</a>(self) -&gt; U</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#545-547" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
</div></div><h3 id="impl-TryFrom%3CU%3E" class="impl"><code class="in-band">impl&lt;T, U&gt; <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;U&gt; for T <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;U: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;T&gt;,&nbsp;</span></code><a href="#impl-TryFrom%3CU%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#589-598" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="associatedtype.Error" class="type"><code>type <a href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" class="type">Error</a> = <a class="enum" href="https://doc.rust-lang.org/nightly/core/convert/enum.Infallible.html" title="enum core::convert::Infallible">Infallible</a></code></h4><div class='docblock'><p>The type returned in the event of a conversion error.</p>
</div><h4 id="method.try_from" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#tymethod.try_from" class="fnname">try_from</a>(value: U) -&gt; <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;T, &lt;T as <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;U&gt;&gt;::<a class="type" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>&gt;</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#595-597" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
</div></div><h3 id="impl-TryInto%3CU%3E" class="impl"><code class="in-band">impl&lt;T, U&gt; <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryInto.html" title="trait core::convert::TryInto">TryInto</a>&lt;U&gt; for T <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;U: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;T&gt;,&nbsp;</span></code><a href="#impl-TryInto%3CU%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#575-584" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="associatedtype.Error-1" class="type"><code>type <a href="https://doc.rust-lang.org/nightly/core/convert/trait.TryInto.html#associatedtype.Error" class="type">Error</a> = &lt;U as <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;T&gt;&gt;::<a class="type" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a></code></h4><div class='docblock'><p>The type returned in the event of a conversion error.</p>
</div><h4 id="method.try_into" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/convert/trait.TryInto.html#tymethod.try_into" class="fnname">try_into</a>(self) -&gt; <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;U, &lt;U as <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;T&gt;&gt;::<a class="type" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>&gt;</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#581-583" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
</div></div></div></section><section id="search" class="content hidden"></section><section class="footer"></section><script>window.rootPath = "../";window.currentCrate = "mio";</script><script src="../main.js"></script><script defer src="../search-index.js"></script></body></html>
Reference in New Issue Copy Permalink