vthread 0.1.0

Bounded carrier-affine virtual threads for Rust
Documentation
# vthread

Carrier-affine virtual threads for Rust.

Write ordinary Rust functions with structured ownership, bounded resources, and explicit
suspension points. The public runtime crate forbids unsafe Rust.

Supported targets are Linux x86_64 and macOS ARM64, with Rust 1.96 or newer and
`panic = "unwind"`. Builds with `panic = "abort"` are rejected.
See [release notes](https://github.com/zsumz/vthread/blob/v0.1.0/RELEASE.md)
for verification coverage and known limitations.

vthread `0.1.0` is production ready within the documented supported workloads and
platforms, with a deliberately limited feature set. Public APIs and supported
contracts remain compatible throughout `0.1.x`; breaking changes require `0.2`.

## A first task

Add vthread to your project:

```toml
[dependencies]
vthread = "=0.1.0"
```

```rust
fn main() -> vthread::Result<()> {
    vthread::run(|scope| {
        let mut task = scope.spawn("answer", || 52)?;
        println!("{}", task.join()?);
        Ok(())
    })
}
```

## Runtime contract

- A started task stays on its carrier thread for its lifetime.
- Scopes own their children. Dropping a handle never detaches work.
- Admission, queues, stacks, timers, wake permits, native work, and channels have explicit bounds.
- Every parked or yielded task has an observable reason. Each park generation selects one
  winner; timers and remote wakes carry the generation they target.
- An operation that reaches a suspension boundary returns `Error::SuspensionDuringPanic`
  instead of switching tasks while its carrier is handling a panic.

The runtime includes cancellation, deadlines, virtual synchronization, bounded channels,
readiness networking, native blocking delegation, diagnostics, and controlled shutdown.

Standard-library blocking calls are not automatically virtualized. Use vthread operations or
`blocking::run` when work may block an OS thread. Cancellation is cooperative and cannot
preempt arbitrary Rust code, native calls, or destructors.

## Runtime evidence

Enable `runtime-evidence` and set a positive `Runtime::builder().evidence_capacity(...)` to
record a bounded, typed event stream. Recording is disabled without that explicit capacity.

- Events cover owned root scopes and supervisors, task and wait lifecycles, wake origins, stacks,
  timers, queues, and shutdown. Borrowed local scopes share their containing owned scope.
- A single consumer can wait for a bounded batch without polling. This blocking wait belongs
  on an ordinary OS or monitoring thread; loss counters report full or disconnected buffers.
- The `qualification` feature adds wake probes bound to one exact wait identity and generation
  for stale-wake testing.

[Source](https://github.com/zsumz/vthread) ยท [Apache License 2.0](LICENSE)