Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
C

corosensei

> 编程语言
Open source

A fast and safe implementation of stackful coroutines in Rust

386 stars0 likes0 views
WebsiteGitHub

About

A fast and safe implementation of stackful coroutines in Rust

corosensei

Documentation

Changelog

Overview

This crate provides a safe and efficient abstraction for context switching between different stacks, in the form of coroutines. A coroutine is a function that can be paused and resumed, yielding values to the caller. A coroutine can suspend itself from any point in its call stack. In addition to receiving yielded values from a coroutine, you can also pass data into the coroutine each time it is resumed.

Example

…

Output

…

Supported targets

This crate currently supports the following targets:

ELF (Linux, BSD, bare metal, etc) Darwin (macOS, iOS, etc) Windows UEFI (no_std)
x86_64 ✅ ✅ ✅ ✅
x86 ✅ ❌ ⚠️* ❌
AArch64 ✅ ✅ ❌ ✅
ARM ✅ ❌ ❌ ❌
RISC-V ✅ ❌ ❌ ❌
LoongArch64 ✅ ❌ ❌ ❌
PowerPC64 ✅ ❌ ❌ ❌

* Linked backtraces are not supported on x86 Windows.

Feel free to open an issue if your target is not supported yet.

Features

Panic propagation

If a panic occurs in a coroutine then the panic will unwind through the coroutine stack and then continue to unwind out of the caller which last resumed it. Once this has happened, the coroutine is considered complete and can no longer be resumed.

…
[main] creating coroutine
[main] resuming coroutine
[coroutine] yielding 42
[main] got value 42 from coroutine
[main] resuming coroutine
[coroutine] panicking
thread 'main' panicked at 'foobar', examples/panic.rs:13:9
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
[main] caught panic "foobar" from coroutine
[main] exiting

Linked backtraces

Backtraces taken from within a coroutine will continue into the parent stack from the point where they were the coroutine was last resumed from. This is a significant help towards debugging issues with code in coroutines.

Notice how the backtrace in this example shows that the coroutine was last resumed from sub_function:

rust
use backtrace::Backtrace;
use corosensei::Coroutine;

#[inline(never)]
fn sub_function(coroutine: &mut Coroutine) {
    coroutine.resume(());
}

fn main() {
    let mut coroutine = Coroutine::new(move |_, ()| {
        let trace = Backtrace::new();
        println!("{:?}", trace);
    });

    sub_function(&mut coroutine);
}
…

Linked backtraces use the platform's standard unwinding metadata and work with debuggers, profilers and many other tools.

Cleanup on drop

If a coroutine is dropped while it is suspended then the coroutine's stack will be safely unwound using the same mechanism as panics, which will drop any local variables on the stack. This is necessary to maintain a safe API: the coroutine's stack cannot be freed or reused while there are still live objects on it.

If this cleanup is not desired then a coroutine can forcibly be marked as completed using the unsafe force_reset function.

Trap handling

For advanced use cases, this crate provides the ability to recover from traps (e.g. segmentation fault, stack overflow) that occur in a coroutine. This API is unsafe and should be used from within a signal/exception handler: it will help set up the return from the signal/exception handler so that the coroutine will exit immediately with the given return value and return control to its parent.

This is particularly useful for running JIT-compiled code with a fixed stack limit: stack overflows can be caught by a signal/exception handler and easily recovered from.

Cargo features

This crate is compatible with #![no_std] when all Cargo features are disabled.

The following Cargo feature flags are available on this crate:

default-stack (Enabled by default)

This feature provides a DefaultStack implementation which can be used by the Coroutine type. This stack is allocated with a guard page using OS APIs and requires std.

If this feature is disabled then you must implement your own stack type which implements the Stack trait.

unwind (Enabled by default)

This feature adds support for:

  • unwinding panics in a coroutine back out to its caller.
  • forcibly unwinding a suspended coroutine via force_unwind or when the coroutine is dropped.

Note that if a coroutine is dropped while suspended (i.e. it has been resumed at least once but has not returned yet) when this feature is disabled then the program will abort.

Requires std.

asm-unwind

This feature uses the asm_unwind nightly feature to allow panics to unwind directly through the inline assembly used in this crate, which can improve performance since it doesn't need to be passed across stack boundaries as a Result.

Implies unwind.

sanitizer

This feature adds support for sanitizers like ASAN which helps detect bugs in unsafe code. Crates like corosensei which perform stack switching need to inform the sanitizer runtime of these stack switches to avoid false positive errors and/or crashes while running with sanitizers enabled.

This feature should not be enabled when not running with sanitizers since it will result in linker errors due to the dependency on the sanitizer runtime API.

Performance

Corosensei has been heavily optimized for performance, to the point where switching stacks only takes a handful of CPU cycles.

Two benchmarks are available via cargo bench:

  • "Coroutine switch" measures the time taken to resume a coroutine and then for that coroutine to yield back to its caller.
  • "Coroutine call" measures the time taken to create a new coroutine which returns immediately, call it and then drop the coroutine.

Benchmark results when running on macOS and Linux:

Arch CPU Frequency Benchmark Time Cycles
AArch64 Apple M1 Max 2.06GHz - 3.22GHz Coroutine switch 3.8665 ns N/A
AArch64 Apple M1 Max 2.06GHz - 3.22GHz Coroutine call 6.4813 ns N/A
AArch64 Apple M3 Max 2.8GHz - 4.05GHz Coroutine switch 1.8212 ns N/A
AArch64 Apple M3 Max 2.8GHz - 4.05GHz Coroutine call 2.6318 ns N/A
x86-64 AMD Ryzen 9 3950X 3.5GHz - 4.7GHz Coroutine switch 4.2867 ns 14.8249
x86-64 AMD Ryzen 9 3950X 3.5GHz - 4.7GHz Coroutine call 5.5082 ns 19.0069
AArch64 ARM Cortex-A72 1.6GHz Coroutine switch 16.278 ns N/A
AArch64 ARM Cortex-A72 1.6GHz Coroutine call 18.769 ns N/A
LoongArch64 Loongson 3A5000 2.3GHz Coroutine switch 9.2831 ns N/A
LoongArch64 Loongson 3A5000 2.3GHz Coroutine call 16.101 ns N/A

Credits

This crate was inspired by the following projects:

  • libfringe
  • Boost.Context
  • wasmtime-fiber
  • async-wormhole

License

Licensed under either of:

  • Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
  • MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Rust

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言