pub struct Registry { /* private fields */ }
Expand description

Registers I/O resources.

Implementations

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(());
        }
    }
}

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)?;

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());

Creates a new independently owned Registry.

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

Trait Implementations

Extracts the raw file descriptor. Read more
Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.