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.

Platforms

Currently supported platforms:

• Linux
• OS X
• Windows
• FreeBSD
• NetBSD
• Android
• iOS

mio can handle interfacing with each of the event notification systems of the aforementioned platforms. The details of their implementation are further discussed in Poll.

Usage

Using mio starts by creating a Poll, which reads events from the OS and put them into Events. You can handle IO events from the OS with it.

For more detail, see Poll.

Example

use mio::*;
use mio::net::{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 a 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

event	Readiness event types and utilities.
net	Networking primitives
unix	Unix only extensions

Structs

Events	A collection of readiness events.
Poll	Polls for readiness events on all registered values.
PollOpt	Options supplied when registering an Evented handle with Poll
Ready	A set of readiness event kinds
Registration	Handle to a user space Poll registration.
SetReadiness	Updates the readiness state of the associated Registration.
Token	Associates readiness notifications with Evented handles.