Crate retty_io

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
• Timer, Channel, Broadcast
• 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 retty-io and are left to the user or higher-level libraries.

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

Platforms

Currently supported platforms:

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

retty-io 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 retty-io 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 retty_io::*;
use retty_io::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!(),
        }
    }
}

Re-exports

pub use event::Events;

Modules

broadcast

Thread safe communication broadcast channel implementing Evented

channel

Thread safe communication channel implementing Evented

event

Readiness event types and utilities.

lazycell

Lazily filled Cell.

net

Networking primitives

timer

Timer optimized for I/O related operations

unix

Unix only extensions

Structs

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.