555 lines
No EOL
58 KiB
HTML
555 lines
No EOL
58 KiB
HTML
<!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="../dark.css">
|
||
<link rel="stylesheet" type="text/css" href="../light.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">☰</div>
|
||
|
||
<p class='location'>Struct Poll</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#methods">Methods</a><div class="sidebar-links"><a href="#method.new">new</a><a href="#method.register">register</a><a href="#method.reregister">reregister</a><a href="#method.deregister">deregister</a><a href="#method.poll">poll</a><a href="#method.poll_interruptible">poll_interruptible</a></div><a class="sidebar-title" href="#implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-Debug">Debug</a><a href="#impl-AsRawFd">AsRawFd</a></div><a class="sidebar-title" href="#synthetic-implementations">Auto Trait Implementations</a><div class="sidebar-links"><a href="#impl-Send">Send</a><a href="#impl-Sync">Sync</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!">
|
||
<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=''>Poll</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'>−</span>]
|
||
</a>
|
||
</span><a class='srclink' href='../src/mio/poll.rs.html#327-343' title='goto source code'>[src]</a></span></h1><div class="docblock type-decl"><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 <code>Evented</code> types,
|
||
waiting until one or more become "ready" for some class of operations; e.g.
|
||
reading and writing. An <code>Evented</code> type is considered ready if it is possible
|
||
to immediately perform a corresponding operation; e.g. <a href="tcp/struct.TcpStream.html#method.read"><code>read</code></a> or
|
||
<a href="tcp/struct.TcpStream.html#method.write"><code>write</code></a>.</p>
|
||
<p>To use <code>Poll</code>, an <code>Evented</code> type must first be registered with the <code>Poll</code>
|
||
instance using the <a href="#method.register"><code>register</code></a> method, 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="#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 <code>Evented</code> handle 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>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">mio</span>::{<span class="ident">Events</span>, <span class="ident">Poll</span>, <span class="ident">Ready</span>, <span class="ident">PollOpt</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="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">"127.0.0.1:0"</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="kw-2">&</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'll store into</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="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="ident">stream</span> <span class="op">=</span> <span class="ident">TcpStream</span>::<span class="ident">connect</span>(<span class="kw-2">&</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">register</span>(<span class="kw-2">&</span><span class="ident">stream</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="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">&</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">&</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">&&</span> <span class="ident">event</span>.<span class="ident">readiness</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>
|
||
<h1 id="edge-triggered-and-level-triggered" class="section-header"><a href="#edge-triggered-and-level-triggered">Edge-triggered and level-triggered</a></h1>
|
||
<p>An <a href="event/trait.Evented.html"><code>Evented</code></a> registration may request edge-triggered events or
|
||
level-triggered events. This is done by setting <code>register</code>'s
|
||
<a href="struct.PollOpt.html"><code>PollOpt</code></a> argument to either <a href="struct.PollOpt.html#method.edge"><code>edge</code></a> or <a href="struct.PollOpt.html#method.level"><code>level</code></a>.</p>
|
||
<p>The difference between the two can be described as follows. Supposed that
|
||
this scenario happens:</p>
|
||
<ol>
|
||
<li>A <a href="tcp/struct.TcpStream.html"><code>TcpStream</code></a> is registered with <code>Poll</code>.</li>
|
||
<li>The socket receives 2kb of data.</li>
|
||
<li>A call to <a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> returns the token associated with the socket
|
||
indicating readable readiness.</li>
|
||
<li>1kb is read from the socket.</li>
|
||
<li>Another call to <a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> is made.</li>
|
||
</ol>
|
||
<p>If when the socket was registered with <code>Poll</code>, edge triggered events were
|
||
requested, then the call to <a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> done in step <strong>5</strong> will
|
||
(probably) hang despite there being another 1kb still present in the socket
|
||
read buffer. The reason for this is that edge-triggered mode delivers events
|
||
only when changes occur on the monitored <a href="event/trait.Evented.html"><code>Evented</code></a>. So, in step <em>5</em> the
|
||
caller might end up waiting for some data that is already present inside the
|
||
socket buffer.</p>
|
||
<p>With edge-triggered events, operations <strong>must</strong> be performed on the
|
||
<code>Evented</code> type until <a href="https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.WouldBlock"><code>WouldBlock</code></a> is returned. In other words, after
|
||
receiving an event indicating readiness for a certain operation, one should
|
||
assume that <a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> may never return another event for the same token
|
||
and readiness until the operation returns <a href="https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.WouldBlock"><code>WouldBlock</code></a>.</p>
|
||
<p>By contrast, when level-triggered notifications was requested, each call to
|
||
<a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> will return an event for the socket as long as data remains
|
||
in the socket buffer. Generally, level-triggered events should be avoided if
|
||
high performance is a concern.</p>
|
||
<p>Since even with edge-triggered events, multiple events can be generated upon
|
||
receipt of multiple chunks of data, the caller has the option to set the
|
||
<a href="struct.PollOpt.html#method.oneshot"><code>oneshot</code></a> flag. This tells <code>Poll</code> to disable the associated <a href="event/trait.Evented.html"><code>Evented</code></a>
|
||
after the event is returned from <a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a>. The subsequent calls to
|
||
<a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> will no longer include events for <a href="event/trait.Evented.html"><code>Evented</code></a> handles that
|
||
are disabled even if the readiness state changes. The handle can be
|
||
re-enabled by calling <a href="#method.reregister"><code>reregister</code></a>. When handles are disabled, internal
|
||
resources used to monitor the handle are maintained until the handle is
|
||
dropped or deregistered. This makes re-registering the handle a fast
|
||
operation.</p>
|
||
<p>For example, in the following scenario:</p>
|
||
<ol>
|
||
<li>A <a href="tcp/struct.TcpStream.html"><code>TcpStream</code></a> is registered with <code>Poll</code>.</li>
|
||
<li>The socket receives 2kb of data.</li>
|
||
<li>A call to <a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> returns the token associated with the socket
|
||
indicating readable readiness.</li>
|
||
<li>2kb is read from the socket.</li>
|
||
<li>Another call to read is issued and <a href="https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.WouldBlock"><code>WouldBlock</code></a> is returned</li>
|
||
<li>The socket receives another 2kb of data.</li>
|
||
<li>Another call to <a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> is made.</li>
|
||
</ol>
|
||
<p>Assuming the socket was registered with <code>Poll</code> with the <a href="struct.PollOpt.html#method.edge"><code>edge</code></a> and
|
||
<a href="struct.PollOpt.html#method.oneshot"><code>oneshot</code></a> options, then the call to <a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> in step 7 would block. This
|
||
is because, <a href="struct.PollOpt.html#method.oneshot"><code>oneshot</code></a> tells <code>Poll</code> to disable events for the socket after
|
||
returning an event.</p>
|
||
<p>In order to receive the event for the data received in step 6, the socket
|
||
would need to be reregistered using <a href="#method.reregister"><code>reregister</code></a>.</p>
|
||
<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
|
||
<a href="event/trait.Evented.html"><code>Evented</code></a> handle 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 notification was received, that the
|
||
associated operation will as well.</p>
|
||
<p>If operation fails with <a href="https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.WouldBlock"><code>WouldBlock</code></a>, then the caller should not treat
|
||
this as an error and wait until another readiness event is received.</p>
|
||
<h3 id="draining-readiness" class="section-header"><a href="#draining-readiness">Draining readiness</a></h3>
|
||
<p>When using edge-triggered mode, once a readiness event is received, the
|
||
corresponding operation must be performed repeatedly until it returns
|
||
<a href="https://doc.rust-lang.org/std/io/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
|
||
<a href="event/trait.Evented.html"><code>Evented</code></a> handle.</p>
|
||
<p>For example, in the first scenario described above, after step 5, even if
|
||
the socket receives more data there is no guarantee that another readiness
|
||
event will be delivered.</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="struct.Ready.html#method.readable"><code>readable</code></a> and <a href="struct.Ready.html#method.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="struct.Ready.html#method.readable"><code>readable</code></a>,
|
||
<a href="unix/struct.UnixReady.html#method.error"><code>error</code></a>, and <a href="unix/struct.UnixReady.html#method.hup"><code>hup</code></a> interest, and either an error or hup 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>hup</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="unix/struct.UnixReady.html#method.hup"><code>hup</code></a> or
|
||
<a href="unix/struct.UnixReady.html#method.error"><code>error</code></a> readiness should be doing so as an <strong>optimization</strong> and always be
|
||
able to handle an error or HUP 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.Evented.html"><code>Evented</code></a> will never become ready unless they are registered with <code>Poll</code>.</p>
|
||
<p>For example:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">mio</span>::{<span class="ident">Poll</span>, <span class="ident">Ready</span>, <span class="ident">PollOpt</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">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">sock</span> <span class="op">=</span> <span class="ident">TcpStream</span>::<span class="ident">connect</span>(<span class="kw-2">&</span><span class="string">"216.58.193.100:80"</span>.<span class="ident">parse</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">register</span>(<span class="kw-2">&</span><span class="ident">sock</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>;</pre>
|
||
<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> Linux </td><td> <a href="http://man7.org/linux/man-pages/man7/epoll.7.html">epoll</a> </td></tr>
|
||
<tr><td> OS X, iOS </td><td> <a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2">kqueue</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> FreeBSD </td><td> <a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2">kqueue</a> </td></tr>
|
||
<tr><td> Android </td><td> <a href="http://man7.org/linux/man-pages/man7/epoll.7.html">epoll</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.EventedFd.html"><code>EventedFd</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.EventedFd.html"><code>EventedFd</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>
|
||
<p>Notifications generated by <a href="struct.SetReadiness.html"><code>SetReadiness</code></a> are handled by an internal
|
||
readiness queue. A single call to <a href="struct.Poll.html#method.poll"><code>Poll::poll</code></a> will collect events from
|
||
both from the system selector and the internal readiness queue.</p>
|
||
</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'><table class='table-display'><tbody><tr><td><code>impl <a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a></code><a href='#impl' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#612-1202' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.new' class="method"><span id='new.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.new' class='fnname'>new</a>() -> <a class="type" href="https://doc.rust-lang.org/nightly/std/io/error/type.Result.html" title="type std::io::error::Result">Result</a><<a class="struct" href="../mio/struct.Poll.html" title="struct mio::Poll">Poll</a>></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#650-666' title='goto source code'>[src]</a></td></tr></tbody></table></span></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-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">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="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="ident">poll</span>,
|
||
<span class="prelude-val">Err</span>(<span class="ident">e</span>) <span class="op">=></span> <span class="macro">panic</span><span class="macro">!</span>(<span class="string">"failed to create Poll instance; err={:?}"</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 `Evented`</span>
|
||
<span class="comment">// handles have been registered with this `Poll` instance.</span>
|
||
<span class="kw">let</span> <span class="ident">n</span> <span class="op">=</span> <span class="ident">poll</span>.<span class="ident">poll</span>(<span class="kw-2">&</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_eq</span><span class="macro">!</span>(<span class="ident">n</span>, <span class="number">0</span>);</pre>
|
||
</div><h4 id='method.register' class="method"><span id='register.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.register' class='fnname'>register</a><E: ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>>(<br> &self, <br> handle: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&</a>E, <br> token: <a class="struct" href="../mio/struct.Token.html" title="struct mio::Token">Token</a>, <br> interest: <a class="struct" href="../mio/struct.Ready.html" title="struct mio::Ready">Ready</a>, <br> opts: <a class="struct" href="../mio/struct.PollOpt.html" title="struct mio::PollOpt">PollOpt</a><br>) -> <a class="type" href="https://doc.rust-lang.org/nightly/std/io/error/type.Result.html" title="type std::io::error::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>> <span class="where fmt-newline">where<br> E: <a class="trait" href="../mio/event/trait.Evented.html" title="trait mio::event::Evented">Evented</a>, </span></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#775-791' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Register an <code>Evented</code> handle with the <code>Poll</code> instance.</p>
|
||
<p>Once registered, the <code>Poll</code> instance will monitor the <code>Evented</code> handle
|
||
for readiness state changes. When it notices a state change, it will
|
||
return a readiness event for the handle the next time <a href="#method.poll"><code>poll</code></a> is
|
||
called.</p>
|
||
<p>See the <a href="#"><code>struct</code></a> docs for a high level overview.</p>
|
||
<h1 id="arguments" class="section-header"><a href="#arguments">Arguments</a></h1>
|
||
<p><code>handle: &E: Evented</code>: This is the handle that the <code>Poll</code> instance
|
||
should monitor for readiness state changes.</p>
|
||
<p><code>token: Token</code>: The caller picks a token to associate with the socket.
|
||
When <a href="#method.poll"><code>poll</code></a> returns an event for the handle, this token is included.
|
||
This allows the caller to map the event to its handle. The token
|
||
associated with the <code>Evented</code> handle can be changed at any time by
|
||
calling <a href="#method.reregister"><code>reregister</code></a>.</p>
|
||
<p><code>token</code> cannot be <code>Token(usize::MAX)</code> as it is reserved for internal
|
||
usage.</p>
|
||
<p>See documentation on <a href="struct.Token.html"><code>Token</code></a> for an example showing how to pick
|
||
<a href="struct.Token.html"><code>Token</code></a> values.</p>
|
||
<p><code>interest: Ready</code>: Specifies which operations <code>Poll</code> should monitor for
|
||
readiness. <code>Poll</code> will only return readiness events for operations
|
||
specified by this argument.</p>
|
||
<p>If a socket is registered with [<code>readable</code>] interest and the socket
|
||
becomes writable, no event will be returned from <a href="#method.poll"><code>poll</code></a>.</p>
|
||
<p>The readiness interest for an <code>Evented</code> handle can be changed at any
|
||
time by calling <a href="#method.reregister"><code>reregister</code></a>.</p>
|
||
<p><code>opts: PollOpt</code>: Specifies the registration options. The most common
|
||
options being <a href="struct.PollOpt.html#method.level"><code>level</code></a> for level-triggered events, <a href="struct.PollOpt.html#method.edge"><code>edge</code></a> for
|
||
edge-triggered events, and <a href="struct.PollOpt.html#method.oneshot"><code>oneshot</code></a>.</p>
|
||
<p>The registration options for an <code>Evented</code> handle can be changed at any
|
||
time by calling <a href="#method.reregister"><code>reregister</code></a>.</p>
|
||
<h1 id="notes" class="section-header"><a href="#notes">Notes</a></h1>
|
||
<p>Unless otherwise specified, the caller should assume that once an
|
||
<code>Evented</code> handle is registered with a <code>Poll</code> instance, it is bound to
|
||
that <code>Poll</code> instance for the lifetime of the <code>Evented</code> handle. This
|
||
remains true even if the <code>Evented</code> handle is deregistered from the poll
|
||
instance using <a href="#method.deregister"><code>deregister</code></a>.</p>
|
||
<p>This function is <strong>thread safe</strong>. It can be called concurrently from
|
||
multiple threads.</p>
|
||
<h1 id="examples-2" class="section-header"><a href="#examples-2">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">Poll</span>, <span class="ident">Ready</span>, <span class="ident">PollOpt</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">time</span>::{<span class="ident">Duration</span>, <span class="ident">Instant</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="kw">let</span> <span class="ident">socket</span> <span class="op">=</span> <span class="ident">TcpStream</span>::<span class="ident">connect</span>(<span class="kw-2">&</span><span class="string">"216.58.193.100:80"</span>.<span class="ident">parse</span>()<span class="question-mark">?</span>)<span class="question-mark">?</span>;
|
||
|
||
<span class="comment">// Register the socket with `poll`</span>
|
||
<span class="ident">poll</span>.<span class="ident">register</span>(<span class="kw-2">&</span><span class="ident">socket</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">1024</span>);
|
||
<span class="kw">let</span> <span class="ident">start</span> <span class="op">=</span> <span class="ident">Instant</span>::<span class="ident">now</span>();
|
||
<span class="kw">let</span> <span class="ident">timeout</span> <span class="op">=</span> <span class="ident">Duration</span>::<span class="ident">from_millis</span>(<span class="number">500</span>);
|
||
|
||
<span class="kw">loop</span> {
|
||
<span class="kw">let</span> <span class="ident">elapsed</span> <span class="op">=</span> <span class="ident">start</span>.<span class="ident">elapsed</span>();
|
||
|
||
<span class="kw">if</span> <span class="ident">elapsed</span> <span class="op">>=</span> <span class="ident">timeout</span> {
|
||
<span class="comment">// Connection timed out</span>
|
||
<span class="kw">return</span> <span class="prelude-val">Ok</span>(());
|
||
}
|
||
|
||
<span class="kw">let</span> <span class="ident">remaining</span> <span class="op">=</span> <span class="ident">timeout</span> <span class="op">-</span> <span class="ident">elapsed</span>;
|
||
<span class="ident">poll</span>.<span class="ident">poll</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">events</span>, <span class="prelude-val">Some</span>(<span class="ident">remaining</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">&</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="comment">// Something (probably) happened on the socket.</span>
|
||
<span class="kw">return</span> <span class="prelude-val">Ok</span>(());
|
||
}
|
||
}
|
||
}</pre>
|
||
</div><h4 id='method.reregister' class="method"><span id='reregister.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.reregister' class='fnname'>reregister</a><E: ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>>(<br> &self, <br> handle: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&</a>E, <br> token: <a class="struct" href="../mio/struct.Token.html" title="struct mio::Token">Token</a>, <br> interest: <a class="struct" href="../mio/struct.Ready.html" title="struct mio::Ready">Ready</a>, <br> opts: <a class="struct" href="../mio/struct.PollOpt.html" title="struct mio::PollOpt">PollOpt</a><br>) -> <a class="type" href="https://doc.rust-lang.org/nightly/std/io/error/type.Result.html" title="type std::io::error::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>> <span class="where fmt-newline">where<br> E: <a class="trait" href="../mio/event/trait.Evented.html" title="trait mio::event::Evented">Evented</a>, </span></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#846-857' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Re-register an <code>Evented</code> handle with the <code>Poll</code> instance.</p>
|
||
<p>Re-registering an <code>Evented</code> handle allows changing the details of the
|
||
registration. Specifically, it allows updating the associated <code>token</code>,
|
||
<code>interest</code>, and <code>opts</code> specified in previous <code>register</code> and <code>reregister</code>
|
||
calls.</p>
|
||
<p>The <code>reregister</code> arguments fully override the previous values. In other
|
||
words, if a socket is registered with <a href="struct.Ready.html#method.readable"><code>readable</code></a> interest and the call
|
||
to <code>reregister</code> specifies <a href="struct.Ready.html#method.writable"><code>writable</code></a>, then read interest is no longer
|
||
requested for the handle.</p>
|
||
<p>The <code>Evented</code> handle must have previously been registered with this
|
||
instance of <code>Poll</code> otherwise the call to <code>reregister</code> will return with
|
||
an error.</p>
|
||
<p><code>token</code> cannot be <code>Token(usize::MAX)</code> as it is reserved for internal
|
||
usage.</p>
|
||
<p>See the <a href="#method.register"><code>register</code></a> documentation for details about the function
|
||
arguments and see the <a href="#"><code>struct</code></a> docs for a high level overview of
|
||
polling.</p>
|
||
<h1 id="examples-3" class="section-header"><a href="#examples-3">Examples</a></h1>
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">mio</span>::{<span class="ident">Poll</span>, <span class="ident">Ready</span>, <span class="ident">PollOpt</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">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="kw">let</span> <span class="ident">socket</span> <span class="op">=</span> <span class="ident">TcpStream</span>::<span class="ident">connect</span>(<span class="kw-2">&</span><span class="string">"216.58.193.100:80"</span>.<span class="ident">parse</span>()<span class="question-mark">?</span>)<span class="question-mark">?</span>;
|
||
|
||
<span class="comment">// Register the socket with `poll`, requesting readable</span>
|
||
<span class="ident">poll</span>.<span class="ident">register</span>(<span class="kw-2">&</span><span class="ident">socket</span>, <span class="ident">Token</span>(<span class="number">0</span>), <span class="ident">Ready</span>::<span class="ident">readable</span>(), <span class="ident">PollOpt</span>::<span class="ident">edge</span>())<span class="question-mark">?</span>;
|
||
|
||
<span class="comment">// Reregister the socket specifying a different token and write interest</span>
|
||
<span class="comment">// instead. `PollOpt::edge()` must be specified even though that value</span>
|
||
<span class="comment">// is not being changed.</span>
|
||
<span class="ident">poll</span>.<span class="ident">reregister</span>(<span class="kw-2">&</span><span class="ident">socket</span>, <span class="ident">Token</span>(<span class="number">2</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>;</pre>
|
||
</div><h4 id='method.deregister' class="method"><span id='deregister.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.deregister' class='fnname'>deregister</a><E: ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>>(&self, handle: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&</a>E) -> <a class="type" href="https://doc.rust-lang.org/nightly/std/io/error/type.Result.html" title="type std::io::error::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>> <span class="where fmt-newline">where<br> E: <a class="trait" href="../mio/event/trait.Evented.html" title="trait mio::event::Evented">Evented</a>, </span></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#902-911' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Deregister an <code>Evented</code> handle with the <code>Poll</code> instance.</p>
|
||
<p>When an <code>Evented</code> handle is deregistered, the <code>Poll</code> instance will
|
||
no longer monitor it for readiness state changes. Unlike disabling
|
||
handles with [<code>oneshot</code>], deregistering clears up any internal resources
|
||
needed to track the handle.</p>
|
||
<p>A handle can be passed back to <code>register</code> after it has been
|
||
deregistered; however, it must be passed back to the <strong>same</strong> <code>Poll</code>
|
||
instance.</p>
|
||
<p><code>Evented</code> handles are automatically deregistered when they are dropped.
|
||
It is common to never need to explicitly call <code>deregister</code>.</p>
|
||
<h1 id="examples-4" class="section-header"><a href="#examples-4">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">Poll</span>, <span class="ident">Ready</span>, <span class="ident">PollOpt</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">time</span>::<span class="ident">Duration</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="kw">let</span> <span class="ident">socket</span> <span class="op">=</span> <span class="ident">TcpStream</span>::<span class="ident">connect</span>(<span class="kw-2">&</span><span class="string">"216.58.193.100:80"</span>.<span class="ident">parse</span>()<span class="question-mark">?</span>)<span class="question-mark">?</span>;
|
||
|
||
<span class="comment">// Register the socket with `poll`</span>
|
||
<span class="ident">poll</span>.<span class="ident">register</span>(<span class="kw-2">&</span><span class="ident">socket</span>, <span class="ident">Token</span>(<span class="number">0</span>), <span class="ident">Ready</span>::<span class="ident">readable</span>(), <span class="ident">PollOpt</span>::<span class="ident">edge</span>())<span class="question-mark">?</span>;
|
||
|
||
<span class="ident">poll</span>.<span class="ident">deregister</span>(<span class="kw-2">&</span><span class="ident">socket</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">// Set a timeout because this poll should never receive any events.</span>
|
||
<span class="kw">let</span> <span class="ident">n</span> <span class="op">=</span> <span class="ident">poll</span>.<span class="ident">poll</span>(<span class="kw-2">&</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_secs</span>(<span class="number">1</span>)))<span class="question-mark">?</span>;
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="number">0</span>, <span class="ident">n</span>);</pre>
|
||
</div><h4 id='method.poll' class="method"><span id='poll.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.poll' class='fnname'>poll</a>(<br> &self, <br> events: &mut <a class="struct" href="../mio/struct.Events.html" title="struct mio::Events">Events</a>, <br> timeout: <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="struct" href="https://doc.rust-lang.org/nightly/core/time/struct.Duration.html" title="struct core::time::Duration">Duration</a>><br>) -> <a class="type" href="https://doc.rust-lang.org/nightly/std/io/error/type.Result.html" title="type std::io::error::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1007-1009' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Wait for readiness events</p>
|
||
<p>Blocks the current thread and waits for readiness events for any of the
|
||
<code>Evented</code> handles 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 <code>Evented</code> handle. 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.Ready.html#method.readable"><code>readable</code></a> and <a href="struct.Ready.html#method.writable"><code>writable</code></a>
|
||
readiness <strong>OR</strong> two separate events may be returned, one with
|
||
<a href="struct.Ready.html#method.readable"><code>readable</code></a> set and one with <a href="struct.Ready.html#method.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><code>poll</code> returns the number of readiness events that have been pushed into
|
||
<code>events</code> or <code>Err</code> when an error has been encountered with the system
|
||
selector. The value returned is deprecated and will be removed in 0.7.0.
|
||
Accessing the events by index is also deprecated. Events can be
|
||
inserted by other events triggering, thus making sequential access
|
||
problematic. Use the iterator API instead. See <a href="struct.Events.html#method.iter"><code>iter</code></a>.</p>
|
||
<p>See the <a href="#">struct</a> level documentation for a higher level discussion of
|
||
polling.</p>
|
||
<h1 id="examples-5" class="section-header"><a href="#examples-5">Examples</a></h1>
|
||
<p>A basic example -- establishing a <code>TcpStream</code> connection.</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">mio</span>::{<span class="ident">Events</span>, <span class="ident">Poll</span>, <span class="ident">Ready</span>, <span class="ident">PollOpt</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">"127.0.0.1:0"</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="kw-2">&</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="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'll store into</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="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="ident">stream</span> <span class="op">=</span> <span class="ident">TcpStream</span>::<span class="ident">connect</span>(<span class="kw-2">&</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">register</span>(<span class="kw-2">&</span><span class="ident">stream</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="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">&</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">&</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">&&</span> <span class="ident">event</span>.<span class="ident">readiness</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><h4 id='method.poll_interruptible' class="method"><span id='poll_interruptible.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.poll_interruptible' class='fnname'>poll_interruptible</a>(<br> &self, <br> events: &mut <a class="struct" href="../mio/struct.Events.html" title="struct mio::Events">Events</a>, <br> timeout: <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="struct" href="https://doc.rust-lang.org/nightly/core/time/struct.Duration.html" title="struct core::time::Duration">Duration</a>><br>) -> <a class="type" href="https://doc.rust-lang.org/nightly/std/io/error/type.Result.html" title="type std::io::error::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1015-1017' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Like <code>poll</code>, but may be interrupted by a signal</p>
|
||
<p>If <code>poll</code> is inturrupted while blocking, it will transparently retry the syscall. If you
|
||
want to handle signals yourself, however, use <code>poll_interruptible</code>.</p>
|
||
</div></div>
|
||
<h2 id='implementations' class='small-section-header'>
|
||
Trait Implementations<a href='#implementations' class='anchor'></a>
|
||
</h2>
|
||
<div id='implementations-list'>
|
||
<h3 id='impl-Debug' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><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.Poll.html" title="struct mio::Poll">Poll</a></code><a href='#impl-Debug' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1212-1217' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.fmt' class="method"><span id='fmt.v' class='invisible'><table class='table-display'><tbody><tr><td><code>fn <a href='https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html#tymethod.fmt' class='fnname'>fmt</a>(&self, fmt: &mut <a class="struct" href="https://doc.rust-lang.org/nightly/core/fmt/struct.Formatter.html" title="struct core::fmt::Formatter">Formatter</a>) -> <a class="type" href="https://doc.rust-lang.org/nightly/core/fmt/type.Result.html" title="type core::fmt::Result">Result</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1213-1216' title='goto source code'>[src]</a></td></tr></tbody></table></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><h3 id='impl-AsRawFd' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>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></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1220-1224' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.as_raw_fd' class="method"><span id='as_raw_fd.v' class='invisible'><table class='table-display'><tbody><tr><td><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>(&self) -> <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></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/mio/poll.rs.html#1221-1223' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><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></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-Send' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><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.Poll.html" title="struct mio::Poll">Poll</a></code><a href='#impl-Send' class='anchor'></a></span></td><td><span class='out-of-band'></span></td></tr></tbody></table></h3><div class='impl-items'></div><h3 id='impl-Sync' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><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.Poll.html" title="struct mio::Poll">Poll</a></code><a href='#impl-Sync' class='anchor'></a></span></td><td><span class='out-of-band'></span></td></tr></tbody></table></h3><div class='impl-items'></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>⏎</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> |