百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
C

corosensei

> 编程语言
开源

在 Rust 中快速、安全地实现堆栈式协程

386 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

在 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 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rust

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

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