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.

Features

• Non-blocking TCP, UDP
• I/O event notification queue backed by epoll, kqueue, and IOCP
• Zero allocations at runtime
• Platform specific extensions

Non-goals

The following are specifically omitted from Mio and are left to the user or higher-level libraries.

• File operations
• Thread pools / multi-threaded event loop
• Timers

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
windows	Windows-only extensions to the mio crate.

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.