Awesome
<div align="center"> <h1>May</h1> <a href="https://github.com/Xudong-Huang/may/actions?query=workflow%3ACI+branch%3Amaster"> <img src="https://github.com/Xudong-Huang/may/workflows/CI/badge.svg"> </a> <a href="https://crates.io/crates/may"> <img src="https://img.shields.io/crates/v/may.svg"> </a> <a href="https://docs.rs/may"> <img src="https://img.shields.io/badge/doc-may-green.svg"> </a>May is a high-performance 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.
</div>Table of contents
Features
- The stackful coroutine implementation is based on generator;
- Support schedule on a configurable number of threads for multi-core systems;
- Support coroutine 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 API;
- All the coroutine API are compatible with the standard library semantics;
- All the coroutine API can be safely called in multi-threaded context;
- Both stable, beta, and nightly channels are supported;
- x86_64 GNU/Linux, x86_64 Windows, x86_64 macOS, AArch64 GNU/Linux, and AArch64 macOS 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 I/O heavy bound examples
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 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 stack size, make sure it's big enough for your applications.
How to tune a stack size
If you want to tune your coroutine 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).