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!(),
        }
    }
}

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

• 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.