aaron1011 / amy Goto Github PK

API Documentation

Add the following to your Cargo.toml

[dependencies]
amy = "0.5"

Add this to your crate root

extern crate amy;

Amy is a Rust library supporting asynchronous I/O by abstracting over the kernel pollers kqueue and epoll. Amy has the following goals behind it's design:

• Clean I/O Abstractions - Don't require users to understand anything about the internals of kernel pollers such as triggering modes, filters, file descriptors, etc...

• Minimal Configuration - In line with clean abstractions, choices of polling modes are made inside the library in order to provide the desired semantics of the library without the user having to understand the low level details

• Performance - Amy performs zero run-time allocations in the poller and registrar after initial startup and limits system calls via non-blocking algorithms where possible

• Minimal implementation - Amy implements just enough code to get the job done. There isn't an abundance of types or traits. The code should also be readable in a linear fashion without jumping from file to file. This should make auditing for both correctness and performance easier.

• Small and consistent API - There are only a few concepts to understand, and a few functions to use.

• Reuse of Rust standard types and traits - Instead of creating a wrapper around every pollable I/O type such as TcpStreams, the library can use the standard library types directly. The only requirement is that these types implement the AsRawFd trait and are pollable by the kernel mechanism.

The best way to get started writing your code with Amy is to take a look at the [Getting Started Guide] (https://github.com/andrewjstone/amy/blob/master/doc/getting_started.md).

Mio is a fantastic project from which Amy has cribbed many ideas. However, the two are distinct in a few specific areas. The core difference is that mio is inherently single threaded: registrations must be made on the same thread as the poller, and the poll loop must be woken up in order to add registrations. In contrast Amy allows registrations to be made on a separate thread from the poller without waking it. Amy also provides a smaller code base dedicated to async network programming. It does not allow arbitrary registration of events with the kernel poller, although this could be easily provided. Like Mio, Amy is a building block and the choice of whether to use one or the other is simply one of preference.

The choice to use Mio or Amy is not necessarily clear, so a short list of features is drawn below, along with some (subjective) use cases showing the reasons to choose either Mio or Amy.

Choose Mio if you:

• Need Windows support
• Are writing a single threaded server
• Want to use the canonical Rust library for Async I/O

Choose Amy if you:

• Only need \*nix support
• Are writing a multi-threaded server requiring cross thread registration
• Want a small, easily auditable library, with little unsafe code
• Are comfortable using something newer and less proven

• Only works on systems that implement epoll and kqueue (Linux, BSDs, Mac OSX, etc...)
• Doesn't work on Windows, although I believe it's possible to implement Poller and Registrar types on top of IOCP