May

https://github.com/xudong-huang/may
Admin
May is a high-performance stackful coroutine library for Rust designed to easily develop and...
Tokens:70,974
Snippets:561
Trust Score:9.4
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Build echo_client example

Source: https://github.com/xudong-huang/may/blob/master/performace.md

Compile the echo_client example in release mode under the project directory.

```sh
$ cargo build --example=echo_client --release
```

--------------------------------

### go! usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/macros.md

Shows how to use the `go!` macro for free spawn and builder spawn. Requires `#[macro_use] extern crate may;` and `use may::coroutine::Builder;`. The free spawn returns a `JoinHandle` that can be joined to get the result.

```rust
#[macro_use] extern crate may;
use may::coroutine::Builder;

let h = go!(move || 42);                       // free spawn
assert_eq!(h.join().unwrap(), 42);

let h2 = go!(Builder::new().stack_size(16 * 1024), move || { /* body */ });
h2.join().unwrap();
```

--------------------------------

### Blocker Usage Example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Example demonstrating how to create a Blocker, share it across coroutines, unpark from another coroutine, and park the current one.

```APIDOC
## Blocker Usage Example

### Description
Example showing how to use Blocker to synchronize between coroutines.

### Code Example
```rust
use may::sync::Blocker;

let blocker = Blocker::new(false);
let b2 = std::sync::Arc::new(blocker);
// in another coroutine: b2.unpark();
b2.park(None).unwrap();
```
```

--------------------------------

### WaitIo usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/io.md

Example of using WaitIo to block until a stream is ready before performing a read.

```rust
use may::io::WaitIo;

// wait until the stream has data, then perform a blocking-free read
let stream = may::net::TcpStream::connect("127.0.0.1:8000").unwrap();
stream.wait_io(); // park until readable/writable event
let mut buf = [0u8; 64];
let n = stream.inner().peek(&mut buf).unwrap();
```

--------------------------------

### AtomicOption Usage Example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Demonstrates initializing an AtomicOption, taking its value, and storing a new value.

```rust
use may::sync::AtomicOption;
let slot = AtomicOption::some(7);
assert_eq!(slot.take(), Some(7));
assert_eq!(slot.take(), None);
slot.store(9);
assert_eq!(slot.take(), Some(9));
```

--------------------------------

### UdpSocket basic usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Demonstrates binding a socket, sending a datagram, and receiving a response.

```rust
use may::net::UdpSocket;

let sock = UdpSocket::bind("127.0.0.1:0").unwrap();
sock.send_to(b"hello", "127.0.0.1:9999").unwrap();
let mut buf = [0u8; 64];
let (n, peer) = sock.recv_from(&mut buf).unwrap();
println!("{n} bytes from {peer}");
```

--------------------------------

### select! usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/macros.md

Example of using select! with a channel, TcpListener, and sleep. The branch that fires first is the one with rx.recv(), so the returned index is 2.

```rust
use may::select;
use may::net::TcpListener;
use may::sync::mpsc::channel;
use std::time::Duration;

let (tx, rx) = channel();
tx.send(42).unwrap();
let listener = TcpListener::bind(("0.0.0.0", 1234)).unwrap();

let id = select!(
    _ = listener.accept() => println!("connected"),
    _ = may::coroutine::sleep(Duration::from_millis(1000)) => {},
    a = rx.recv() => println!("rx = {a:?}")   // this branch wins -> id == 2
);
assert_eq!(id, 2);
```

--------------------------------

### CoIo usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/io.md

Demonstrates wrapping a standard UdpSocket in a CoIo and performing a read operation within a coroutine.

```rust
use may::io::CoIo;
use std::net::UdpSocket;
use std::io::Read;

// wrap an existing std socket in a CoIo
let sock = UdpSocket::bind("127.0.0.1:0").unwrap();
let mut cio = CoIo::new(sock).unwrap();

let mut buf = [0u8; 128];
let n = mio_read(&mut cio, &mut buf); // Read::read inside a coroutine

fn mio_read(r: &mut impl Read, buf: &mut [u8]) -> usize {
    r.read(buf).unwrap()
}
```

--------------------------------

### UnixDatagram usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/os-unix-net.md

Demonstrates binding a socket, sending a datagram, and receiving it.

```rust
use may::os::unix::net::{UnixDatagram, UnixListener};
use std::io::prelude::*;

let listener = UnixDatagram::bind("/tmp/dg1.sock").unwrap();
let sock = UnixDatagram::unbound().unwrap();
sock.send_to(b"hello", "/tmp/dg1.sock").unwrap();
let mut buf = [0u8; 32];
let (n, addr) = listener.recv_from(&mut buf).unwrap();
assert_eq!(&buf[..n], b"hello");
```

--------------------------------

### join! usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/macros.md

Shows how to use join! to run two expensive computations in parallel. Both bodies complete before join! returns.

```rust
// both bodies run in parallel, both complete before join! returns
join!(
    expensive_computation_a(),
    expensive_computation_b(),
);
```

--------------------------------

### SyncFlag usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Demonstrates creating a SyncFlag, firing it from a coroutine, and waiting for the signal.

```rust
use may::sync::SyncFlag;
let flag = std::sync::Arc::new(SyncFlag::new());
let f2 = flag.clone();
let h = may::go!(move || { f2.fire(); });
flag.wait();          // returns as soon as the coroutine fires
assert!(flag.is_fired());
h.join().unwrap();
```

--------------------------------

### loop_select! usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/macros.md

Example of using loop_select! with a TcpListener. The loop_select! call is commented out, but it would handle connections forever and never return.

```rust
use may::loop_select;

let listener = may::net::TcpListener::bind(("0.0.0.0", 4321)).unwrap();
// loop_select!(
//     _ = listener.accept() => println!("got a connection"),
// );
// unreachable after this point
```

--------------------------------

### Complete configuration example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/config.md

Demonstrates setting worker count, pool capacity, stack size, and timeout before spawning coroutines. Configuration must be applied before any spawn or IO operations.

```rust
fn main() {
    // must run before any spawn / IO
    may::config()
        .set_workers(4)             // 4 worker (=event-loop) threads
        .set_pool_capacity(500)     // recycle up to 500 coroutine stacks
        .set_stack_size(64 * 1024)  // default coroutine stack 64 KiB
        .set_timeout_ns(5_000_000); // epoll wait 5 ms
    may::config().set_worker_pin(true);

    // verify
    assert_eq!(may::config().get_workers(), 4);
    assert_eq!(may::config().get_pool_capacity(), 500);
    assert_eq!(may::config().get_stack_size(), 64 * 1024);
}
```

--------------------------------

### UnixListener usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/os-unix-net.md

Demonstrates binding to a socket, accepting connections, and spawning asynchronous tasks to handle stream data.

```rust
use may::os::unix::net::UnixListener;
use std::io::{Read, Write};

let listener = UnixListener::bind("/tmp/may.sock").unwrap();
while let Ok((mut stream, _)) = listener.accept() {
    may::go!(move || {
        let mut buf = [0u8; 512];
        while let Ok(n) = stream.read(&mut buf) {
            if n == 0 { break; }
            stream.write_all(&buf[..n]).unwrap();
        }
    });
}
```

--------------------------------

### Barrier Usage Example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Demonstrates using a Barrier to synchronize two concurrent tasks using may::go!.

```rust
use may::sync::Barrier;
let barrier = std::sync::Arc::new(Barrier::new(2));
let b2 = barrier.clone();
let h = may::go!(move || { barrier.wait(); });
barrier.wait();
h.join().unwrap();
```

--------------------------------

### Usage example with two consumers

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/channels.md

Shows how to create a channel, send values, check pressure, and use a cloned receiver with two concurrent consumers.

```rust
use may::sync::mpmc;

let (tx, rx) = mpmc::channel();
for i in 0..4 { tx.send(i).unwrap(); }
assert_eq!(tx.pressure(), 4);

// two consumers
let rx2 = rx.clone();
let c1 = may::go!(move || { for _ in 0..2 { rx.recv().unwrap(); } });
let c2 = may::go!(move || { for _ in 0..2 { rx2.recv().unwrap(); } });
c1.join().unwrap();
c2.join().unwrap();
```

--------------------------------

### TcpListener usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Demonstrates binding a listener and handling incoming connections in separate coroutines.

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

let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
while let Ok((mut stream, _)) = listener.accept() {
    may::go!(move || {
        let mut buf = [0u8; 1024];
        while let Ok(n) = stream.read(&mut buf) {
            if n == 0 { break; }
            stream.write_all(&buf[..n]).unwrap();
        }
    });
}
```

--------------------------------

### Blocker usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Demonstrates creating a new Blocker, wrapping it in an Arc, and using it to park and unpark across coroutines.

```rust
use may::sync::Blocker;

let blocker = Blocker::new(false);
let b2 = std::sync::Arc::new(blocker);
// in another coroutine: b2.unpark();
b2.park(None).unwrap();
```

--------------------------------

### Builder::spawn usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/coroutine.md

Example of using Builder::new().name().stack_size().spawn() to create and run a coroutine. The spawn call is unsafe and returns an io::Result.

```rust
use may::coroutine::Builder;

let handler = unsafe {
    Builder::new().name("worker".into()).stack_size(64 * 1024).spawn(|| {
        // coroutine code
    }).unwrap()
};
handler.join().unwrap();
```

--------------------------------

### UnixStream usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/os-unix-net.md

Demonstrates connecting to a Unix socket, writing data, and reading the response using standard I/O traits.

```rust
use may::os::unix::net::UnixStream;
use std::io::{Read, Write};

let mut stream = UnixStream::connect("/tmp/may.sock").unwrap();
stream.write_all(b"hello world").unwrap();
let mut response = String::new();
stream.read_to_string(&mut response).unwrap();
```

--------------------------------

### config()

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/config.md

Returns a Config instance for configuring the may runtime. Must be called at program start before any coroutine or IO operation.

```APIDOC
## config()

### Description
Returns a Config instance for configuring the may runtime. Must be called at program start before any coroutine or IO operation.

### Method
Function

### Endpoint
`pub fn config() -> Config`

### Parameters
None

### Response
- **Config** - The configuration instance.

```

--------------------------------

### Integration with macros example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/cqueue.md

Shows how to use `select!` and `loop_select!` macros to build cqueues. The `select!` macro returns the index of the branch that fired, while `loop_select!` runs forever handling all events.

```rust
use may::{select, loop_select};
use may::net::TcpListener;
use std::time::Duration;

let listener = TcpListener::bind(("0.0.0.0", 1234)).unwrap();

let id = select!(
    _ = listener.accept() => println!("connected"),
    _ = may::coroutine::sleep(Duration::from_millis(1000)) => {},
    a = may::sync::mpsc::channel::<i32>().1.recv() => println!("rx {a:?}"),
);
// id is the index (0-based) of the branch that fired

// loop_select! runs forever, handling all events
// loop_select!(
//     _ = listener.accept() => println!("connected"),
// );
```

--------------------------------

### Splitting a TcpStream for Concurrent Use

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/io.md

Example showing how to split a TcpStream and use the resulting reader and writer in separate coroutines.

```rust
use may::io::SplitIo;
use std::io::{Read, Write};

let stream = may::net::TcpStream::connect("127.0.0.1:8000").unwrap();
let (mut reader, mut writer) = stream.split().unwrap();

// hand the halves to different coroutines
let h1 = may::go!(move || {
    let mut b = [0u8; 32];
    let _ = reader.read(&mut b);
});
let h2 = may::go!(move || {
    let _ = writer.write_all(b"request");
    let _ = writer.flush();
});
h1.join().unwrap();
h2.join().unwrap();
```

--------------------------------

### WaitGroup usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Demonstrates using WaitGroup to coordinate multiple coroutines by cloning the group and dropping it upon completion.

```rust
use may::sync::WaitGroup;
let wg = WaitGroup::new();
for _ in 0..4 {
    let wg = wg.clone();
    may::go!(move || {
        // do work
        drop(wg); // signal completion
    });
}
wg.wait(); // returns after all 4 coroutines dropped their clone
```

--------------------------------

### mpsc channel usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/channels.md

Demonstrates creating a channel, sending values, receiving with recv and recv_timeout, and detecting disconnection when the sender is dropped.

```rust
use may::sync::mpsc;

let (tx, rx) = mpsc::channel();
tx.send(1).unwrap();
tx.send(2).unwrap();
assert_eq!(rx.recv(), Ok(1));
assert_eq!(rx.recv_timeout(std::time::Duration::from_millis(100)), Ok(2));

// disconnect detection
drop(tx);
assert_eq!(rx.recv(), Err(std::sync::mpsc::RecvError));
```

--------------------------------

### Semphore Usage Example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Demonstrates using a Semphore to manage access to a critical section with a permit count of 2.

```rust
use may::sync::Semphore;
let sem = std::sync::Arc::new(Semphore::new(2));
let s2 = sem.clone();
let h = may::go!(move || { s2.wait(); /* critical section */ s2.post(); });
sem.wait();
sem.post();
h.join().unwrap();
```

--------------------------------

### may::queue::mpsc::Queue usage

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/channels.md

Example demonstrating the usage of the multi-producer single-consumer bounded-segment queue.

```rust
use may::queue::mpsc::Queue;

let q = Queue::<u32>::new();
q.push(1);
q.push(2);
assert!(q.pop() == Some(1));
assert!(!q.is_empty());
```

--------------------------------

### Mutex Usage Example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Demonstrates creating a Mutex, locking it to modify the inner value, and consuming the mutex to retrieve the final result.

```rust
use may::sync::Mutex;

let m = Mutex::new(0);
let mut guard = m.lock().unwrap();
*guard += 1;
drop(guard);
assert_eq!(m.into_inner().unwrap(), 1);
```

--------------------------------

### go_with! usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/macros.md

Shows how to use the `go_with!` macro to spawn a coroutine with a stack size, and optionally with a name. The first call uses a stack size of 64 KiB, the second adds a name 'my-co'.

```rust
let h = go_with!(64 * 1024, move || { /* body */ });
let h2 = go_with!("my-co", 64 * 1024, move || { /* body */ });
```

--------------------------------

### Connecting with TcpStream

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Example usage of connecting to a remote address and optionally using a timeout if the io_timeout feature is enabled.

```rust
use may::net::TcpStream;
use std::time::Duration;

let stream = TcpStream::connect("127.0.0.1:8000").unwrap();

#[cfg(feature = "io_timeout")]
let _s2 = TcpStream::connect_timeout(&"10.255.255.1:80".parse().unwrap(), Duration::from_secs(2));
```

--------------------------------

### Condvar usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Demonstrates using Condvar with a Mutex to synchronize state between a spawned coroutine and the main thread.

```rust
use may::sync::{Condvar, Mutex};

let pair = std::sync::Arc::new((Mutex::new(false), Condvar::new()));
let p2 = pair.clone();
may::go!(move || {
    let (lock, cvar) = &*p2;
    let mut guard = lock.lock().unwrap();
    *guard = true;
    cvar.notify_one();
});

let (lock, cvar) = &*pair;
let mut guard = lock.lock().unwrap();
while !*guard {
    guard = cvar.wait(guard).unwrap();
}
assert!(*guard);
```

--------------------------------

### Configure may runtime and spawn a coroutine

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/configuration.md

Configure the may runtime first, then spawn and join a coroutine. The scheduler starts lazily on the first spawn or I/O. The io_timeout feature enables an optional timeout setting.

```rust
fn main() {
    // configure first!
    may::config()
        .set_workers(8)
        .set_stack_size(128 * 1024)
        .set_pool_capacity(2048)
        .set_worker_pin(true);
    #[cfg(feature = "io_timeout")]
    may::config().set_timeout_ns(5_000_000);

    // scheduler is lazily started by the first spawn/io
    let h = may::go!(|| println!("running"));
    h.join().unwrap();
}
```

--------------------------------

### JoinHandle::join example: spawn and join a coroutine, handle panic

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/coroutine.md

Shows how to use coroutine::spawn and JoinHandle::join to retrieve a coroutine's result and to observe panic propagation. The first coroutine increments an atomic counter and returns 7; join().unwrap() yields 7. The second coroutine panics, and join().is_err() confirms the panic is isolated.

```rust
use may::coroutine;
use std::sync::atomic::{AtomicUsize, Ordering};

let counter = std::sync::Arc::new(AtomicUsize::new(0));
let c = counter.clone();
let h = unsafe { coroutine::spawn(move || {
    c.fetch_add(1, Ordering::SeqCst);
    7
}) };
assert_eq!(h.join().unwrap(), 7);
assert_eq!(counter.load(Ordering::SeqCst), 1);

// panic propagation, isolated from other coroutines
let h2 = unsafe { coroutine::spawn(|| { panic!("boom"); }) };
assert!(h2.join().is_err());
```

--------------------------------

### may::sync::spsc channel usage

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/channels.md

Example demonstrating creating an SPSC channel, sending a value, and receiving it. Note that Sender and Receiver do not implement Clone.

```rust
use may::sync::spsc;

let (tx, rx) = spsc::channel();
tx.send(42).unwrap();
assert_eq!(rx.recv(), Ok(42));
```

--------------------------------

### Using may::sync::RwLock read and write guards

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Example usage of may::sync::RwLock: create a lock with RwLock::new, acquire a read guard with read().unwrap(), then a write guard with write().unwrap() and mutate the value. Demonstrates Deref and DerefMut behavior on the guards.

```rust
use may::sync::RwLock;

let lock = RwLock::new(5u32);
{
    let r = lock.read().unwrap();
    assert_eq!(*r, 5);
}
let mut w = lock.write().unwrap();
*w += 1;
assert_eq!(*w, 6);
```

--------------------------------

### Usage example: sending and polling an event

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/cqueue.md

Demonstrates creating a cqueue scope, adding a select coroutine that sends an event with extra=7, and polling with a 1-second timeout. The returned event's token is asserted to be 0.

```rust
use may::cqueue;
use std::time::Duration;

let id = cqueue::scope(|cqueue| {
    // cqueue_add_oneshot! and cqueue_add! are the standard way to populate
    cqueue.add(0, |es| {
        es.send(7); // top half: produce an event with extra=7
    });
    let ev = cqueue.poll(Some(Duration::from_secs(1))).unwrap();
    ev.token
});
assert_eq!(id, 0);
```

--------------------------------

### Builder::spawn_local

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/coroutine.md

Same as spawn but immediately starts the coroutine on the current thread (first run run_coroutine(co)) instead of enqueueing it. Doc note: you should always use spawn instead of this API.

```APIDOC
## Builder::spawn_local

### Description
Same as spawn but immediately starts the coroutine on the current thread (first run run_coroutine(co)) instead of enqueueing it. Doc note: you should always use spawn instead of this API.

### Method
spawn_local

### Signature
pub unsafe fn spawn_local<F, T>(self, f: F) -> io::Result<JoinHandle<T>>
where
    F: FnOnce() -> T + Send + 'static,
    T: Send + 'static,

### Parameters
- **f** (F: FnOnce() -> T + Send + 'static) - Required - The coroutine body.

### Returns
io::Result<JoinHandle<T>> - Err on failure to create at the OS level.

### Source
src/coroutine_impl.rs:373
```

--------------------------------

### coroutine_local! usage example

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/macros.md

Example usage of coroutine_local! to create a per-coroutine counter. Each coroutine gets its own value; when accessed from a plain thread context it falls back to a thread-local backend. The comment notes that the thread context saw 1 increment while each coroutine saw its own counter.

```rust
use may::coroutine_local;

coroutine_local! {
    static COUNTER: std::cell::Cell<u32> = std::cell::Cell::new(0);
}

let inc = || {
    COUNTER.with(|c| c.set(c.get() + 1));
};
inc();
let h1 = may::go!(move || { inc(); inc(); });
let h2 = may::go!(move || { inc(); });
h1.join().unwrap();
h2.join().unwrap();
// thread context saw 1 increment; each coroutine saw its own counter
```

--------------------------------

### Error handling patterns in may coroutines

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/errors.md

Comprehensive example covering six error-handling patterns in the `may` coroutine library: recovering from spawn failures via `Builder::spawn`, distinguishing `ParkError::Timeout` vs `ParkError::Canceled` on `Blocker::park`, handling channel disconnects with `mpsc::RecvError` and `TryRecvError::Disconnected`, converting a failed `CoIo::new` error into `std::io::Error`, isolating panics in child coroutines, and recovering a poisoned `Mutex` guard via `into_inner()`. Note that `some_std_socket` is a placeholder for an actual socket object.

```rust
use may::coroutine;
use may::sync::{Blocker, mpsc};

// 1. Recover from spawn failure via Builder
let handler = unsafe {
    coroutine::Builder::new().spawn(|| 1).map_err(|e| e.kind())
};
match handler {
    Ok(h) => { let _ = h.join(); }
    Err(kind) => println!("spawn failed: {kind:?}"),
}

// 2. Distinguish cancel vs timeout on park-based primitives
let b = std::sync::Arc::new(Blocker::new(false));
match b.park(Some(std::time::Duration::from_millis(100))) {
    Ok(()) => {}
    Err(may::coroutine::ParkError::Timeout) => println!("timed out"),
    Err(may::coroutine::ParkError::Canceled) => println!("cancelled"),
}

// 3. Channel disconnects / timeouts
let (tx, rx) = mpsc::channel::<i32>();
drop(tx);
assert!(matches!(rx.recv(), Err(std::sync::mpsc::RecvError)));
assert!(matches!(
    rx.try_recv(),
    Err(std::sync::mpsc::TryRecvError::Disconnected)
));

// 4. Recover the object from a failed CoIo conversion
match may::io::CoIo::new(some_std_socket) {
    Ok(co) => drop(co),
    Err(e) => {
        let err: std::io::Error = e.into(); // or: e.into_data();
        println!("{err}");
    }
}

// 5. Panic isolation: a child panic never affects other coroutines
let bad = unsafe { coroutine::spawn(|| { panic!("boom"); }) };
assert!(bad.join().is_err()); // panic payload is contained in the handle

// 6. Poison handling on locks
let m = may::sync::Mutex::new(0u32);
match m.lock() {
    Ok(g) => drop(g),
    Err(poisoned) => drop(poisoned.into_inner()), // recover the guard
}
assert!(m.is_poisoned());
```

--------------------------------

### Coroutine::stack_size

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/coroutine.md

Gets the coroutine stack size.

```APIDOC
## Coroutine::stack_size

### Description
Gets the coroutine stack size.

### Method
stack_size

### Signature
pub fn stack_size(&self) -> usize

### Parameters
None

### Returns
- **usize** - The stack size of the coroutine.

```

--------------------------------

### UdpSocket::ttl / set_ttl

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Gets or sets the IP_TTL option.

```APIDOC
## UdpSocket::ttl / set_ttl

### Description
Gets or sets the IP_TTL option.

### Signatures
pub fn ttl(&self) -> io::Result<u32>
pub fn set_ttl(&self, ttl: u32) -> io::Result<()>

### Parameters (set_ttl)
- **ttl** (u32) - Required - The TTL value.

### Returns
- **ttl**: io::Result<u32> - Current TTL.
- **set_ttl**: io::Result<()> - Ok or an error.
```

--------------------------------

### UdpSocket::multicast_loop_v6 / set_multicast_loop_v6

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Gets or sets the IPV6_MULTICAST_LOOP option.

```APIDOC
## UdpSocket::multicast_loop_v6 / set_multicast_loop_v6

### Description
Gets or sets the IPV6_MULTICAST_LOOP option.

### Signatures
pub fn multicast_loop_v6(&self) -> io::Result<bool>
pub fn set_multicast_loop_v6(&self, on: bool) -> io::Result<()>

### Parameters (set_multicast_loop_v6)
- **on** (bool) - Required - Whether to enable multicast loop.

### Returns
- **multicast_loop_v6**: io::Result<bool> - Current value.
- **set_multicast_loop_v6**: io::Result<()> - Ok or an error.
```

--------------------------------

### Implement a naive echo server with May

Source: https://github.com/xudong-huang/may/blob/master/README.md

A basic TCP echo server using the may::net::TcpListener and the go! macro to handle connections concurrently.

```rust
#[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();
            }
        });
    }
}
```

--------------------------------

### UdpSocket::multicast_ttl_v4 / set_multicast_ttl_v4

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Gets or sets the IP_MULTICAST_TTL option.

```APIDOC
## UdpSocket::multicast_ttl_v4 / set_multicast_ttl_v4

### Description
Gets or sets the IP_MULTICAST_TTL option.

### Signatures
pub fn multicast_ttl_v4(&self) -> io::Result<u32>
pub fn set_multicast_ttl_v4(&self, ttl: u32) -> io::Result<()>

### Parameters (set_multicast_ttl_v4)
- **ttl** (u32) - Required - The TTL value.

### Returns
- **multicast_ttl_v4**: io::Result<u32> - Current TTL.
- **set_multicast_ttl_v4**: io::Result<()> - Ok or an error.
```

--------------------------------

### UdpSocket::broadcast / set_broadcast

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Gets or sets the SO_BROADCAST option.

```APIDOC
## UdpSocket::broadcast / set_broadcast

### Description
Gets or sets the SO_BROADCAST option.

### Signatures
pub fn broadcast(&self) -> io::Result<bool>
pub fn set_broadcast(&self, on: bool) -> io::Result<()>

### Parameters (set_broadcast)
- **on** (bool) - Required - Whether to enable broadcast.

### Returns
- **broadcast**: io::Result<bool> - Current value.
- **set_broadcast**: io::Result<()> - Ok or an error.
```

--------------------------------

### UdpSocket::multicast_loop_v4 / set_multicast_loop_v4

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Gets or sets the IP_MULTICAST_LOOP option for IPv4.

```APIDOC
## UdpSocket::multicast_loop_v4 / set_multicast_loop_v4

### Description
Gets or sets the IP_MULTICAST_LOOP option for IPv4.

### Signatures
pub fn multicast_loop_v4(&self) -> io::Result<bool>
pub fn set_multicast_loop_v4(&self, on: bool) -> io::Result<()>

### Parameters (set_multicast_loop_v4)
- **on** (bool) - Required - Whether to enable multicast loop.

### Returns
- **multicast_loop_v4**: io::Result<bool> - Current value.
- **set_multicast_loop_v4**: io::Result<()> - Ok or an error.
```

--------------------------------

### UdpSocket Timeouts

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Methods for setting and getting read and write timeouts, available with the io_timeout feature.

```APIDOC
## UdpSocket Timeouts

### Description
Methods for setting and getting read and write timeouts, available with the io_timeout feature.

### Methods
- **set_read_timeout** - Sets the read timeout.
- **set_write_timeout** - Sets the write timeout.
- **read_timeout** - Gets the read timeout.
- **write_timeout** - Gets the write timeout.

These methods have identical signatures to those on TcpStream.
```

--------------------------------

### UnixListener::accept

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/os-unix-net.md

Accepts the next connection on the UnixListener.

```APIDOC
## UnixListener::accept

### Description
Accepts the next incoming connection on the listener.

### Method
accept

### Signature
pub fn accept(&self) -> io::Result<(UnixStream, SocketAddr)>

### Returns
io::Result<(UnixStream, SocketAddr)> - A tuple containing the accepted UnixStream and the peer's SocketAddr.

### Notes
Uses the UnixListenerAccept resource when not immediately ready.

### Source
net.rs:434
```

--------------------------------

### new

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/sync.md

Creates a new unlocked RwLock.

```APIDOC
## `new`

### Description
Creates a new unlocked RwLock.

### Method
`pub fn new(t: T) -> RwLock<T>`

### Parameters
- `t` (T) - Required - The initial value to store in the lock.

### Returns
- `RwLock<T>` - A new unlocked lock.

### Source
`rwlock.rs:58`
```

--------------------------------

### UnixListener::accept method

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/os-unix-net.md

Accepts the next incoming connection, utilizing the UnixListenerAccept resource if the connection is not immediately ready.

```rust
pub fn accept(&self) -> io::Result<(UnixStream, SocketAddr)>
```

--------------------------------

### UnixListener::incoming

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/os-unix-net.md

Returns an iterator over incoming connections.

```APIDOC
## UnixListener::incoming

### Description
Returns an iterator over incoming connections.

### Method
incoming

### Signature
pub fn incoming(&self) -> Incoming<'_>

### Returns
Incoming<'_> - An iterator yielding io::Result<UnixStream> for each connection.

### Source
net.rs:534
```

--------------------------------

### go_with! — spawn with name/stack size

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/macros.md

The `go_with!` macro provides two forms to spawn a coroutine with a custom stack size and optionally a name. It builds a `Builder` with the specified settings and spawns the coroutine.

```APIDOC
## go_with! — spawn with name/stack size

### Description
Spawns a coroutine with a specified stack size and optionally a name. The macro constructs a `Builder` with the given settings and spawns the coroutine.

### Macro Signature
```rust
macro_rules! go_with {
    // for stack_size
    ($stack_size:expr, $func:expr) => { ... };
    // for name and stack_size
    ($name: expr, $stack_size:expr, $func:expr) => { ... };
}
```

### Forms

#### 1. Stack size only
- **Syntax**: `go_with!(stack_size, closure)`
- **Behavior**: Builds `Builder::new().stack_size(stack_size)` and spawns the closure.

#### 2. Name and stack size
- **Syntax**: `go_with!(name, stack_size, closure)`
- **Behavior**: Builds `Builder::new().name(name.to_owned()).stack_size(stack_size)` and spawns the closure.

### Example
```rust
let h = go_with!(64 * 1024, move || { /* body */ });
let h2 = go_with!("my-co", 64 * 1024, move || { /* body */ });
```
```

--------------------------------

### config() free function

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/config.md

Retrieves the global Config instance.

```rust
pub fn config() -> Config   // src/config.rs:29
```

--------------------------------

### Incoming

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/os-unix-net.md

Iterator over incoming connections.

```APIDOC
## Incoming

### Description
An iterator over incoming connections on a UnixListener.

### Type
pub struct Incoming<'a>

### Iterator Implementation
impl Iterator for Incoming<'_> { type Item = io::Result<UnixStream>; ... }

### Source
net.rs:595
```

--------------------------------

### Run echo_client against Tokio server

Source: https://github.com/xudong-huang/may/blob/master/performace.md

Run the echo_client with 100 clients, 100 bytes, 8 threads, targeting 127.0.0.1:8080. The output shows benchmark results: 153496 request/sec.

```sh
$ cargo run --example=echo_client --release -- -c 100 -l 100 -t 8 -a 127.0.0.1:8080
    Finished release [optimized] target(s) in 5.86s
     Running `target/release/examples/echo_client -c 100 -l 100 -t 8 -a '127.0.0.1:8080'`
==================Benchmarking: 127.0.0.1:8080==================
100 clients, running 100 bytes, 10 sec.

Speed: 153496 request/sec,  153495 response/sec, 14989 kb/sec
Requests: 1534961
Responses: 1534958
```

--------------------------------

### CoIo Timeout Methods

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/io.md

Methods to get and set read and write timeouts for the CoIo wrapper, available when the `io_timeout` feature is enabled.

```APIDOC
## CoIo Timeout Methods

### Description
Get and set read and write timeouts for the CoIo wrapper. Available with the `io_timeout` feature.

### Methods
- `pub fn read_timeout(&self) -> io::Result<Option<Duration>>`
- `pub fn write_timeout(&self) -> io::Result<Option<Duration>>`
- `pub fn set_read_timeout(&self, dur: Option<Duration>) -> io::Result<()>`
- `pub fn set_write_timeout(&self, dur: Option<Duration>) -> io::Result<()>`
```

--------------------------------

### Run echo_client against May server

Source: https://github.com/xudong-huang/may/blob/master/performace.md

Run the echo_client with 100 clients, 100 bytes, 8 threads, targeting 127.0.0.1:8000. The output shows benchmark results: 256155 request/sec.

```sh
$ cargo run --example=echo_client --release -- -c 100 -l 100 -t 8 -a 127.0.0.1:8000
    Finished release [optimized] target(s) in 11.77s
     Running `target/release/examples/echo_client -c 100 -l 100 -t 8 -a '127.0.0.1:8000'`
==================Benchmarking: 127.0.0.1:8000==================
100 clients, running 100 bytes, 10 sec.

Speed: 256155 request/sec,  256155 response/sec, 25015 kb/sec
Requests: 2561559
Responses: 2561554
```

--------------------------------

### CoIo::new constructor

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/io.md

Creates a new CoIo instance, registering the file descriptor with the event loop and setting it to non-blocking mode.

```rust
pub fn new(io: T) -> Result<Self, Error<T>>
```

--------------------------------

### set_workers

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/config.md

Sets the number of worker threads. Must be called before the scheduler starts. A value of 0 uses the internal default (number of CPUs).

```APIDOC
## set_workers

### Description
Sets the number of worker threads. Must be called before the scheduler starts. A value of 0 uses the internal default (number of CPUs).

### Method
Function

### Endpoint
`pub fn set_workers(&self, workers: usize) -> &Self`

### Parameters
#### Path Parameters
- **workers** (usize) - Required - Number of worker threads. 0 means internal default (number of CPUs).

### Response
- **&Self** - The Config instance for chaining.

```

--------------------------------

### Builder::new method

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/coroutine.md

Base configuration for a new Builder. Defaults: name = None, stack_size = None (falls back to config().get_stack_size()), id = None (any worker thread).

```rust
pub fn new() -> Builder
```

--------------------------------

### Unsafe Thread Local Storage pattern in coroutines

Source: https://github.com/xudong-huang/may/blob/master/README.md

An example of an unsafe pattern where coroutine scheduling occurs between setting and using Thread Local Storage.

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

--------------------------------

### coroutine_local!

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/macros.md

Declares a static coroutine-local variable. Each coroutine gets its own value initialized on first access; falls back to thread-local storage in plain thread contexts.

```APIDOC
## coroutine_local!

### Description
Declares a static coroutine-local variable. Each coroutine gets its own value initialized on first access; falls back to thread-local storage in plain thread contexts.

### Syntax
rust
macro_rules! coroutine_local {
    (static $NAME:ident : $t:ty = $e:expr) => { ... };
}


### Parameters
- **$NAME** (ident) - Required - The name of the static variable.
- **$t** (ty) - Required - The type of the variable.
- **$e** (expr) - Required - The initializer expression.

### Behavior
- Each coroutine gets its own value.
- When accessed from a plain thread context, it falls back to a thread-local backend.
- The value must be `'static` and is destroyed when the coroutine finishes.

### Example
rust
use may::coroutine_local;

coroutine_local! {
    static COUNTER: std::cell::Cell<u32> = std::cell::Cell::new(0);
}

let inc = || {
    COUNTER.with(|c| c.set(c.get() + 1));
};
inc();
let h1 = may::go!(move || { inc(); inc(); });
let h2 = may::go!(move || { inc(); });
h1.join().unwrap();
h2.join().unwrap();
// thread context saw 1 increment; each coroutine saw its own counter

```

--------------------------------

### set_pool_capacity / get_pool_capacity

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/config.md

Sets or gets the coroutine pool capacity. The pool pre-creates dummy coroutine stacks up to the capacity, and put discards coroutines beyond capacity.

```APIDOC
## set_pool_capacity / get_pool_capacity

### Description
Sets or gets the coroutine pool capacity. The pool pre-creates that many dummy coroutine stacks, and put discards coroutines beyond capacity.

### Method
N/A (Rust methods)

### Endpoint
N/A (Rust methods)

### Parameters
#### Parameters
- **capacity** (usize) - Required - 0 → internal default (DEFAULT_POOL_CAPACITY = 1000)

### Request Example
N/A

### Response
#### Success Response
- **get_pool_capacity** returns usize - The current pool capacity.

#### Response Example
N/A
```

--------------------------------

### TcpListener::bind method

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Creates a listening socket. On Unix, it sets SO_REUSEADDR and SO_REUSEPORT; on Windows, it sets SO_REUSEADDR only. The listen backlog is set to 1024.

```rust
pub fn bind<A: ToSocketAddrs>(addr: A) -> io::Result<TcpListener>
```

--------------------------------

### Coroutine::name method and usage

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/coroutine.md

Returns the name of the coroutine if one was set via Builder::name. The example demonstrates setting a name and cancelling a running coroutine.

```rust
pub fn name(&self) -> Option<&str>
```

```rust
use may::coroutine::{self, Builder};

let h = unsafe {
    Builder::new().name("my-co".to_owned()).spawn(|| 1).unwrap()
};
assert_eq!(h.coroutine().name(), Some("my-co"));

// cancel a coroutine
let h2 = unsafe { coroutine::spawn(|| loop { coroutine::yield_now(); }) };
unsafe { h2.coroutine().cancel() };
assert!(h2.join().is_err());
```

--------------------------------

### TcpListener::accept method

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Accepts a new connection, returning the stream and peer address. It performs a fast non-blocking accept attempt first on Unix.

```rust
pub fn accept(&self) -> io::Result<(TcpStream, SocketAddr)>
```

--------------------------------

### EventSender::send method and usage

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/cqueue.md

Queues an event with an extra payload and yields the coroutine. The usage example demonstrates adding a coroutine to a cqueue scope and sending a value.

```rust
pub fn send(&self, extra: usize)
```

```rust
use may::cqueue;

cqueue::scope(|cq| {
    cq.add(0, |es| {
        let tok = es.get_token();
        es.send(tok * 2); // extra = 0
    });
});
```

--------------------------------

### UnixDatagram constructors

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/os-unix-net.md

Methods to create new UnixDatagram instances.

```rust
pub fn bind<P: AsRef<Path>>(path: P) -> io::Result<UnixDatagram>      // net.rs:656
pub fn unbound() -> io::Result<UnixDatagram>                          // net.rs:676
pub fn pair() -> io::Result<(UnixDatagram, UnixDatagram)>             // net.rs:698
```

--------------------------------

### TcpListener::bind

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/net.md

Creates a listening socket via socket2. On Unix, sets SO_REUSEADDR and SO_REUSEPORT; on Windows, sets SO_REUSEADDR only. The listen backlog is 1024.

```APIDOC
## TcpListener::bind

### Description
Creates a listening socket via socket2. On Unix, sets SO_REUSEADDR and SO_REUSEPORT; on Windows, sets SO_REUSEADDR only. The listen backlog is 1024.

### Signature
pub fn bind<A: ToSocketAddrs>(addr: A) -> io::Result<TcpListener>

### Parameters
- **addr** (A: ToSocketAddrs) - Required - Bind address; the first resolved address is used

### Returns
io::Result<TcpListener>
```

--------------------------------

### get_timeout_ns / set_timeout_ns

Source: https://github.com/xudong-huang/may/blob/master/_autodocs/api-reference/config.md

Gets or sets the IO poll timeout in nanoseconds. Only compiled with the io_timeout feature (default on). Without the feature the event loop uses a hardcoded 1 s timeout.

```APIDOC
## get_timeout_ns / set_timeout_ns

### Description
Gets or sets the IO poll timeout in nanoseconds. Only compiled with the io_timeout feature (default on). Without the feature the event loop uses a hardcoded 1 s timeout.

### Method
N/A (Rust methods)

### Endpoint
N/A (Rust methods)

### Parameters
#### Parameters
- **timeout** (u64) - Required - Poll wait in nanoseconds (default 10,000,000 ns = 10 ms)

### Request Example
N/A

### Response
#### Success Response
- **get_timeout_ns** returns u64 - The current timeout in nanoseconds.

#### Response Example
N/A
```
Tokens:
Raw