Crate mio

A fast, low-level IO library for Rust focusing on non-blocking APIs, event notification, and other useful utilities for building high performance IO apps.

Goals

• Fast - minimal overhead over the equivalent OS facilities (epoll, kqueue, etc...)
• Zero allocations
• A scalable readiness-based API, similar to epoll on Linux
• Design to allow for stack allocated buffers when possible (avoid double buffering).
• Provide utilities such as a timers, a notification channel, buffer abstractions, and a slab.

Usage

Using mio starts by creating an EventLoop, which handles receiving events from the OS and dispatching them to a supplied Handler.

Example

use mio::*;
use mio::tcp::{TcpListener, TcpStream};

// Setup some tokens to allow us to identify which event is
// for which socket.
const SERVER: Token = Token(0);
const CLIENT: Token = Token(1);

let addr = "127.0.0.1:13265".parse().unwrap();

// Setup the server socket
let server = TcpListener::bind(&addr).unwrap();

// Create an poll instance
let poll = Poll::new().unwrap();

// Start listening for incoming connections
poll.register(&server, SERVER, Ready::readable(),
              PollOpt::edge()).unwrap();

// Setup the client socket
let sock = TcpStream::connect(&addr).unwrap();

// Register the socket
poll.register(&sock, CLIENT, Ready::readable(),
              PollOpt::edge()).unwrap();

// Create storage for events
let mut events = Events::with_capacity(1024);

loop {
    poll.poll(&mut events, None).unwrap();

    for event in events.iter() {
        match event.token() {
            SERVER => {
                // Accept and drop the socket immediately, this will close
                // the socket and notify the client of the EOF.
                let _ = server.accept();
            }
            CLIENT => {
                // The server just shuts down the socket, let's just exit
                // from our event loop.
                return;
            }
            _ => unreachable!(),
        }
    }
}

Modules

channel	Thread safe communication channel implementing Evented
deprecated	EventLoop and other deprecated types
tcp	Primitives for working with TCP
timer	Timer optimized for I/O related operations
udp	Primitives for working with UDP
unix	Unix only extensions

Structs

Event	An readiness event returned by Poll.
Events	A buffer for I/O events to get placed into, passed to Poll::poll.
EventsIter	Iterate an Events structure
Poll	Polls for readiness events on all registered values.
PollOpt	Configures readiness polling behavior for a given Evented value.
Ready	A set of readiness events returned by Poll.
Registration	Handle to a Poll registration. Used for registering custom types for event notifications.
SetReadiness	Used to update readiness for an associated Registration. SetReadiness is Sync which allows it to be updated across threads.
Token	Used to identify which Evented value is associated with an Event notification returned by Poll.

Traits

Evented

A value that may be registered with an EventLoop

Functions

would_block

Returns a std WouldBlock error without allocating