## Registry

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

Source

#### 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§

Source§

### impl AsRawFd for Registry

Source§

#### fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor. Read more
Source§

### impl Debug for Registry

Source§

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

Formats the value using the given formatter. Read more

## Auto Trait Implementations§

§

### impl Freeze for Registry

§

### impl RefUnwindSafe for Registry

§

### impl Send for Registry

§

### impl Sync for Registry

§

### impl Unpin for Registry

§

### impl UnwindSafe for Registry

## Blanket Implementations§

Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

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

Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.