Crate mio [] [src]

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

windows

Windows-only extensions to the mio crate.

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

IoVec
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