may Rust Stackful Coroutine Library

When writing programs with May, follow these four rules to ensure performance and stability:

1. Avoid thread-blocking APIs: Calling standard library functions that block the entire OS thread will degrade the performance of the entire scheduler.
2. Handle Thread Local Storage (TLS) carefully: Accessing TLS in a coroutine can be unsafe if scheduling occurs between setting and using the TLS. It is considered unsafe to use the following pattern if the code is sensitive to state:

   set_tls();
   // Any coroutine API that causes scheduling (e.g., coroutine::yield_now())
   use_tls();

   It is safe if there is no coroutine scheduling between the set and use calls, or if your code is not sensitive to the previous state.
3. Avoid long-running CPU-bound tasks: Long tasks can impact fairness unless you do not care about task scheduling fairness.
4. Prevent stack overflow: Each coroutine has a fixed stack size with a guard page. Exceeding this stack will trigger a segmentation fault. Ensure your coroutine stack size is appropriately tuned for your application's needs.

In a coroutine-based environment, using standard Thread Local Storage (TLS) via the thread_local! macro is unsafe for storing state that should be specific to a coroutine. Because a coroutine can be rescheduled onto different threads during its lifecycle, accessing TLS can lead to inconsistent or outdated values.

To ensure each coroutine has its own unique local storage, use Coroutine Local Storage (CLS) provided by the coroutine_local! macro.

Key behaviors of CLS:

• Coroutine Context: Guarantees unique storage per coroutine.
• Thread Context: If you access a CLS variable from a standard thread context, it safely falls back to its TLS storage based on the provided key.

To migrate from TLS to CLS in Rust, replace the thread_local! macro with coroutine_local!.

fn coroutine_local_many() {
    use std::sync::atomic::{AtomicUsize, Ordering};
    coroutine_local!(static FOO: AtomicUsize = AtomicUsize::new(0));

    coroutine::scope(|scope| {
        for i in 0..10 {
            go!(scope, move || {
                FOO.with(|f| {
                    assert_eq!(f.load(Ordering::Relaxed), 0);
                    f.store(i, Ordering::Relaxed);
                    assert_eq!(f.load(Ordering::Relaxed), i);
                });
            });
        }
    });
    // called in thread
    FOO.with(|f| {
        assert_eq!(f.load(Ordering::Relaxed), 0);
    });
}

May is a high-performance library for programming stackful coroutines in Rust, designed to enable the development of massive concurrent programs. It is conceptually similar to Goroutines in Go.

Key features include:

• Stackful Coroutines: Implementation based on generators.
• Multi-core Support: Scheduling on a configurable number of threads.
• Coroutine Local Storage (CLS): Support for local storage specific to a coroutine.
• Efficient I/O and Timers: Optimized asynchronous network I/O and timer management.
• Synchronization Primitives: Includes semaphores, MPMC channels, and more.
• Robustness: Support for coroutine cancellation, graceful panic handling (panics do not affect other coroutines), and scoped coroutine creation.
• Safety and Compatibility: APIs are compatible with standard library semantics and are safe to call in multi-threaded contexts. It supports stable, beta, and nightly Rust channels on x86_64 GNU/Linux, Windows, and macOS.

A Semphore is a synchronization primitive that allows threads and coroutines to synchronize their actions using an integer value.

• post(): Increments the semaphore value. If there are waiting threads or coroutines, one is woken up.
• wait(): Decrements the semaphore value. If the value is zero, the caller blocks until a post() is called.
• try_wait(): Attempts to decrement the value without blocking. Returns true if successful, false if the value is zero.
• wait_timeout(dur): Similar to wait(), but returns false if the specified Duration elapses before the semaphore is acquired.
• get_value(): Returns the current semaphore value (returns 0 if the value is negative, indicating waiters).

use std::sync::Arc;
use may::coroutine;
use may::sync::Semphore;

let sem = Arc::new(Semphore::new(0));
let sem2 = sem.clone();

// spawn a coroutine, and then wait for it to start
unsafe {
    coroutine::spawn(move || {
        sem2.post();
    });
}

// wait for the coroutine to start up
sem.wait();

A SyncFlag is a boolean synchronization primitive that acts like a barrier. It allows multiple threads or coroutines to synchronize their actions.

• When the flag is false, any thread or coroutine calling wait() or wait_timeout() will block until the flag is set to true.
• When the flag is true, any thread or coroutine calling wait() or wait_timeout() will return immediately.
• Once the flag is set to true via fire(), it remains true and will never become false again.

This primitive is useful for ensuring that a specific event has occurred (like a coroutine starting up) before proceeding with execution.

use std::sync::Arc;
use may::coroutine;
use may::sync::SyncFlag;

let flag = Arc::new(SyncFlag::new());
let flag2 = flag.clone();

// spawn a coroutine, and then wait for it to start
unsafe {
    coroutine::spawn(move || {
        flag2.fire();
        flag2.wait();
    });
}

// wait for the coroutine to start up
flag.wait();

A WaitGroup enables threads to synchronize the beginning or end of some computation. It allows a main thread (or any thread) to block until all registered tasks have completed.

Key Differences from std::sync::Barrier:

• Registration: Unlike a Barrier which requires a fixed number of threads at construction, a WaitGroup is registered by cloning it. Each clone represents a new participant.
• Reusability: A Barrier can be reused after synchronization; a WaitGroup synchronizes threads only once.
• Blocking Behavior: In a Barrier, all threads wait for each other. With a WaitGroup, individual threads can choose to either wait for others using .wait() or continue without blocking by simply dropping their reference.

Basic Usage Pattern

1. Create a WaitGroup using WaitGroup::new().
2. Clone the WaitGroup for every spawned thread/task.
3. Inside the task, perform work and then drop the clone (or let it go out of scope).
4. Call .wait() on the original WaitGroup instance to block until all clones are dropped.

use may::sync::WaitGroup;
use std::thread;

// Create a new wait group.
let wg = WaitGroup::new();

for _ in 0..4 {
    // Create another reference to the wait group.
    let wg = wg.clone();

    thread::spawn(move || {
        // Do some work.

        // Drop the reference to the wait group.
        drop(wg);
    });
}

// Block until all threads have finished their work.
wg.wait();