Crate mio

source · []
Expand description

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

convert 🔒

Readiness event types and utilities.

event_imp 🔒
io 🔒
lazycell 🔒

This crate provides a LazyCell struct which acts as a lazily filled Cell.

Networking primitives

poll 🔒
sys 🔒
token 🔒

Unix only extensions

Structs

A collection of readiness events.

Polls for readiness events on all registered values.

Options supplied when registering an Evented handle with Poll

A set of readiness event kinds

Handle to a user space Poll registration.

Updates the readiness state of the associated Registration.

Associates readiness notifications with Evented handles.