Struct mio::Registry

pub struct Registry { /* private fields */ }

Registers I/O resources.

Implementations

impl Registry

pub fn register<S>(
    &self,
    source: &mut S,
    token: Token,
    interests: Interest
) -> Result<()>where
    S: Source + ?Sized,

Register an event::Source with the Poll instance.

Once registered, the Poll instance will monitor the event source 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 Poll docs for a high level overview.

Arguments

source: &mut S: event::Source: This is the source of events that the Poll instance should monitor for readiness state changes.

token: Token: The caller picks a token to associate with the socket. When poll returns an event for the handle, this token is included. This allows the caller to map the event to its source. The token associated with the event::Source can be changed at any time by calling reregister.

See documentation on Token for an example showing how to pick Token values.

interest: Interest: Specifies which operations Poll should monitor for readiness. Poll will only return readiness events for operations specified by this argument.

If a socket is registered with readable interest and the socket becomes writable, no event will be returned from poll.

The readiness interest for an event::Source can be changed at any time by calling reregister.

Notes

Callers must ensure that if a source being registered with a Poll instance was previously registered with that Poll instance, then a call to deregister has already occurred. Consecutive calls to register is unspecified behavior.

Unless otherwise specified, the caller should assume that once an event source is registered with a Poll instance, it is bound to that Poll instance for the lifetime of the event source. This remains true even if the event source is deregistered from the poll instance using deregister.

Examples

use mio::{Events, Poll, Interest, Token};
use mio::net::TcpStream;
use std::net::SocketAddr;
use std::time::{Duration, Instant};

let mut poll = Poll::new()?;

let address: SocketAddr = "127.0.0.1:0".parse()?;
let listener = net::TcpListener::bind(address)?;
let mut socket = TcpStream::connect(listener.local_addr()?)?;

// Register the socket with `poll`
poll.registry().register(
    &mut socket,
    Token(0),
    Interest::READABLE | Interest::WRITABLE)?;

let mut events = Events::with_capacity(1024);
let start = Instant::now();
let timeout = Duration::from_millis(500);

loop {
    let elapsed = start.elapsed();

    if elapsed >= timeout {
        // Connection timed out
        return Ok(());
    }

    let remaining = timeout - elapsed;
    poll.poll(&mut events, Some(remaining))?;

    for event in &events {
        if event.token() == Token(0) {
            // Something (probably) happened on the socket.
            return Ok(());
        }
    }
}

pub fn reregister<S>(
    &self,
    source: &mut S,
    token: Token,
    interests: Interest
) -> Result<()>where
    S: Source + ?Sized,

Re-register an event::Source with the Poll instance.

Re-registering an event source allows changing the details of the registration. Specifically, it allows updating the associated token and interests specified in previous register and reregister calls.

The reregister arguments fully override the previous values. In other words, if a socket is registered with readable interest and the call to reregister specifies writable, then read interest is no longer requested for the handle.

The event source must have previously been registered with this instance of Poll, otherwise the behavior is unspecified.

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

Examples

use mio::{Poll, Interest, Token};
use mio::net::TcpStream;
use std::net::SocketAddr;

let poll = Poll::new()?;

let address: SocketAddr = "127.0.0.1:0".parse()?;
let listener = net::TcpListener::bind(address)?;
let mut socket = TcpStream::connect(listener.local_addr()?)?;

// Register the socket with `poll`, requesting readable
poll.registry().register(
    &mut socket,
    Token(0),
    Interest::READABLE)?;

// Reregister the socket specifying write interest instead. Even though
// the token is the same it must be specified.
poll.registry().reregister(
    &mut socket,
    Token(0),
    Interest::WRITABLE)?;

pub fn deregister<S>(&self, source: &mut S) -> Result<()>where
    S: Source + ?Sized,

Deregister an event::Source with the Poll instance.

When an event source is deregistered, the Poll instance will no longer monitor it for readiness state changes. Deregistering clears up any internal resources needed to track the handle. After an explicit call to this method completes, it is guaranteed that the token previously registered to this handle will not be returned by a future poll, so long as a happens-before relationship is established between this call and the poll.

The event source must have previously been registered with this instance of Poll, otherwise the behavior is unspecified.

A handle can be passed back to register after it has been deregistered; however, it must be passed back to the same Poll instance, otherwise the behavior is unspecified.

Examples

use mio::{Events, Poll, Interest, Token};
use mio::net::TcpStream;
use std::net::SocketAddr;
use std::time::Duration;

let mut poll = Poll::new()?;

let address: SocketAddr = "127.0.0.1:0".parse()?;
let listener = net::TcpListener::bind(address)?;
let mut socket = TcpStream::connect(listener.local_addr()?)?;

// Register the socket with `poll`
poll.registry().register(
    &mut socket,
    Token(0),
    Interest::READABLE)?;

poll.registry().deregister(&mut socket)?;

let mut events = Events::with_capacity(1024);

// Set a timeout because this poll should never receive any events.
poll.poll(&mut events, Some(Duration::from_secs(1)))?;
assert!(events.is_empty());

pub fn try_clone(&self) -> Result<Registry>

Creates a new independently owned Registry.

Event sources registered with this Registry will be registered with the original Registry and Poll instance.

Trait Implementations

impl AsRawFd for Registry

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Registry

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.