Struct mio_pool::poll::Poll

pub struct Poll(_);

Polls for readiness events on all registered file descriptors.

Poll allows a program to monitor a large number of file descriptors, waiting until one or more become “ready” for some class of operations; e.g. reading and writing. A file descriptor is considered ready if it is possible to immediately perform a corresponding operation; e.g. read.

These Poll instances are optimized for a worker pool use-case, and so they are all oneshot, edge-triggered, and only support “ready to read”.

To use Poll, a file descriptor must first be registered with the Poll instance using the register method. A Token is also passed to the register function, and that same Token is returned when the given file descriptor is ready.

Examples

A basic example – establishing a TcpStream connection.

use mio_pool::poll::{Events, Poll, Token};
use mio::net::TcpStream;

use std::net::{TcpListener, SocketAddr};

// Bind a server socket to connect to.
let addr: SocketAddr = "127.0.0.1:0".parse()?;
let server = TcpListener::bind(&addr)?;

// Construct a new `Poll` handle as well as the `Events` we'll store into
let poll = Poll::new()?;
let mut events = Events::with_capacity(1024);

// Connect the stream
let stream = TcpStream::connect(&server.local_addr()?)?;

// Register the stream with `Poll`
poll.register(&stream, Token(0))?;

// Wait for the socket to become ready. This has to happens in a loop to
// handle spurious wakeups.
loop {
    poll.poll(&mut events, None)?;

    for Token(t) in &events {
        if t == 0 {
            // The socket connected (probably; it could be a spurious wakeup)
            return Ok(());
        }
    }
}

Exclusive access

Since this Poll implementation is optimized for worker-pool style use-cases, all file descriptors are registered using EPOLL_ONESHOT. This means that once an event has been issued for a given descriptor, not more events will be issued for that descriptor until it has been re-registered using reregister.

Implementations

impl Poll

pub fn new() -> Result<Self>

Return a new Poll handle.

This function will make a syscall to the operating system to create the system selector. If this syscall fails, Poll::new will return with the error.

See struct level docs for more details.

Examples

use mio_pool::poll::{Poll, Events};
use std::time::Duration;

let poll = match Poll::new() {
    Ok(poll) => poll,
    Err(e) => panic!("failed to create Poll instance; err={:?}", e),
};

// Create a structure to receive polled events
let mut events = Events::with_capacity(1024);

// Wait for events, but none will be received because no `Evented`
// handles have been registered with this `Poll` instance.
let n = poll.poll(&mut events, Some(Duration::from_millis(500)))?;
assert_eq!(n, 0);

pub fn register(&self, file: &dyn AsRawFd, t: Token) -> Result<()>

Register a file descriptor with this Poll instance.

Once registered, the Poll instance monitors the given descriptor for readiness state changes. When it notices a state change, it will return a readiness event for the handle the next time [poll] is called.

See the [struct] docs for a high level overview.

token is user-defined value that is associated with the given file. When [poll] returns an event for file, this token is included. This allows the caller to map the event back to its descriptor. The token associated with a file descriptor can be changed at any time by calling [reregister].

pub fn reregister(&self, file: &dyn AsRawFd, t: Token) -> Result<()>

Re-register a file descriptor with this Poll instance.

When you re-register a file descriptor, you can change the details of the registration. Specifically, you can update the token specified in previous register and reregister calls.

See the register documentation for details about the function arguments and see the struct docs for a high level overview of polling.

pub fn deregister(&self, file: &dyn AsRawFd) -> Result<()>

Deregister a file descriptor from this Poll instance.

When you deregister a file descriptor, it will no longer be modified for readiness events, and it will no longer produce events from poll.

pub fn poll(
    &self,
    events: &mut Events,
    timeout: Option<Duration>
) -> Result<usize>

Wait for events on file descriptors associated with this Poll instance.

Blocks the current thread and waits for events for any of the file descriptors that are registered with this Poll instance. The function blocks until either at least one readiness event has been received or timeout has elapsed. A timeout of None means that poll blocks until a readiness event has been received.

The supplied events will be cleared and newly received readiness events will be pushed onto the end. At most events.capacity() events will be returned. If there are further pending readiness events, they are returned on the next call to poll.

Note that once an event has been issued for a given token (or rather, for the token’s file descriptor), no further events will be issued for that descriptor until it has been re-registered. Note also that the timeout is 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.

poll returns the number of events that have been pushed into events, or Err when an error has been encountered with the system selector.

See the struct level documentation for a higher level discussion of polling.