impl Registry

fn register<S>(self: &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 std::error::Error;
# use std::net;
# fn main() -> Result<(), Box<dyn Error>> {
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(());
        }
    }
}
# }

fn reregister<S>(self: &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 std::error::Error;
# use std::net;
# fn main() -> Result<(), Box<dyn Error>> {
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)?;
#     Ok(())
# }

fn deregister<S>(self: &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 std::error::Error;
# use std::net;
# fn main() -> Result<(), Box<dyn Error>> {
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());
#     Ok(())
# }

fn try_clone(self: &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.

impl AsRawFd for Registry

fn as_raw_fd(self: &Self) -> RawFd

impl Debug for Registry

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

impl Freeze for Registry

impl RefUnwindSafe for Registry

impl Send for Registry

impl Sync for Registry

impl Unpin for Registry

impl UnsafeUnpin for Registry

impl UnwindSafe for Registry

impl<T> Any for Registry

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Registry

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Registry

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> From for Registry

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for Registry

fn into(self: Self) -> U

Calls U::from(self).

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

impl<T, U> TryFrom for Registry

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Registry

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>