May

May is a high-performant library for programming stackful coroutines with which you can easily develop and maintain massive concurrent programs. It can be thought as the Rust version of the popular Goroutine.

Table of contents

• Features
• Usage
• More examples
  • The CPU heavy load examples
  • The I/O heavy bound examples
• Performance
• Caveat
• How to tune a stack size
• License

Features

• The stackful coroutine's implementation is based on generator;
• Support schedule on a configurable number of threads for multi-core systems;
• Support coroutine's version of a local storage (CLS);
• Support efficient asynchronous network I/O;
• Support efficient timer management;
• Support standard synchronization primitives, a semaphore, an MPMC channel, etc;
• Support cancellation of coroutines;
• Support graceful panic handling that will not affect other coroutines;
• Support scoped coroutine creation;
• Support general selection for all the coroutine's API;
• All the coroutine's API are compatible with the standard library semantics;
• All the coroutine's API can be safely called in multi-threaded context;
• Both stable, beta, and nightly channels are supported;
• Both x86_64 GNU/Linux, x86_64 Windows, x86_64 Mac OS are supported.

Usage

A naive echo server implemented with May:

#[macro_use]
extern crate may;

use may::net::TcpListener;
use std::io::{Read, Write};

fn main() {
    let listener = TcpListener::bind("127.0.0.1:8000").unwrap();
    while let Ok((mut stream, _)) = listener.accept() {
        go!(move || {
            let mut buf = vec![0; 1024 * 16]; // alloc in heap!
            while let Ok(n) = stream.read(&mut buf) {
                if n == 0 {
                    break;
                }
                stream.write_all(&buf[0..n]).unwrap();
            }
        });
    }
}

More examples

The CPU heavy load examples

• The "Quick Sort" algorithm
• A prime number generator

The I/O heavy bound examples

• An echo server
• An echo client
• A simple HTTP
• A simple HTTPS
• WebSockets

Performance

You can refer to https://tfb-status.techempower.com/ to get the latest may_minihttp comparisons with other most popular frameworks.

Caveat

There is a detailed document that describes May's main restrictions. In general, there are four things you should follow when writing programs that use coroutines:

• Don't call thread-blocking API (It will hurt the performance);
• Carefully use Thread Local Storage (access TLS in coroutine might trigger undefined behavior).

It's considered unsafe with the following pattern:

set_tls();
// Or another coroutine's API that would cause scheduling:
coroutine::yield_now(); 
use_tls();

but it's safe if your code is not sensitive about the previous state of TLS. Or there is no coroutines scheduling between set TLS and use TLS.

• Don't run CPU bound tasks for long time, but it's ok if you don't care about fairness;
• Don't exceed the coroutine stack. There is a guard page for each coroutine stack. When stack overflow occurs, it will trigger segment fault error.

Note:

The first three rules are common when using cooperative asynchronous libraries in Rust. Even using a futures-based system also have these limitations. So what you should really focus on is a coroutine's stack size, make sure it's big enough for your applications.

How to tune a stack size

If you want to tune your coroutine's stack size, please check out this document.

License

May is licensed under either of the following, at your option:

• The Apache License v2.0.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0);
• The MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT).