Struct Registry

source

pub struct Registry { /* private fields */ }

Expand description

Registers I/O resources.

Implementations§

source §

impl Registry

source

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

source

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

source

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