bugthesystem / may

rust stackful coroutine library

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