compio README

The project's README from github.com/compio-rs/compio. As one markdown file: README.md.

Compio

MIT licensed crates.io docs.rs Check Test Telegram Discord

A thread-per-core Rust runtime with IOCP/io_uring/polling inspired by monoio.

Quick start

Add compio as dependency:

cargo add compio --features macros,fs

Then use the high level APIs provided to perform filesystem & network IO:

use compio::{fs::File, io::AsyncReadAtExt};

#[compio::main]
async fn main() {
    let file = File::open("Cargo.toml").await.unwrap();
    let (read, buffer) = file.read_to_end_at(Vec::with_capacity(1024), 0).await.unwrap();
    assert_eq!(read, buffer.len());
    let buffer = String::from_utf8(buffer).unwrap();
    println!("{}", buffer);
}

It's also possible to use the low-level driver (the proactor, without async executor) manually. See driver example.

Observability

The console feature makes the runtime emit the tracing spans and events that tokio-console consumes, so compio applications can be inspected with it:

cargo add compio --features console
cargo add console-subscriber

# .cargo/config.toml
#
# `console-subscriber` refuses to run unless the runtime is known to be
# instrumented; this is the escape hatch it provides for runtimes other than
# tokio.
[build]
rustflags = ["--cfg", "console_without_tokio_unstable"]

console_subscriber::init();
compio::runtime::Runtime::new().unwrap().block_on(async {
    // ...
});

Then run tokio-console to watch tasks, poll times and waker activity. The console module docs describe what is reported and what is not.

The console example runs an echo server on a dispatcher, so that the console shows the tasks of a thread-per-core application spread over its worker threads, next to tasks that are wrong in the ways it warns about. It passes the cfg on the command line instead:

RUSTFLAGS="--cfg console_without_tokio_unstable" \
    cargo run --example console --features console,time,net,dispatcher,sync

Why the name?

The name comes from "completion-based IO", and follows the non-existent convention that an async runtime should be named with a suffix "io".

Comparison with other runtimes

Tokio

Tokio is a great generic-purpose async runtime. However, it is poll-based, and even uses undocumented APIs on Windows. We would like some new high-level APIs to perform IOCP/io_uring.

compio isn't tokio-based. This is mainly because tokio doesn't expose APIs to control mio, and mio doesn't expose APIs to control IOCP.

Monoio

Monoio focuses on Linux and io-uring, and fallbacks to mio on other platforms.

Glommio

Glommio doesn't support Windows.

Others

There are also lots of other great async runtimes. But most of them are (at the moment when compio was created) either poll-based, use io-uring unsoundly, or aren't cross-platform. We hope compio can fill this gap.

Contributing

There are opportunities to contribute to Compio at any level. It doesn't matter if you are just getting started with Rust or are the most weathered expert, we can use your help. If you have any question about Compio, feel free to join our telegram group. Before contributing, please checkout our contributing guide.

compio (compio-rs/compio)

Searching Database…

1.9K ·GitHub
Compio
这是什么？Compio 是一个 thread-per-core（每核一线程）的 Rust 异步运行时，它使用基于完成的 IO 后端（Windows 上是 IOCP，Linux 上是 io_uring，其他平台用轮询），而不是大多数运行时采用的基于轮询的模型。
这是添加到我 Rust 项目里的库，还是独立的服务器？它是一个 Rust 库（crate），添加为依赖后即可获得异步文件系统和网络 IO，还有一个可以直接使用的底层驱动。
我该怎么上手？在 Cargo.toml 中把 compio 添加为依赖，然后使用它面向文件系统和网络 IO 的高级异步 API；如果需要更多控制权，也可以手动改用底层的 proactor 驱动。
除了 Rust，使用它还需要别的吗？只需要 Rust 和 compio crate；它在 Linux 上依赖 io_uring，在 Windows 上依赖 IOCP，在其他平台则回退到轮询，这些都由它内部处理。
它和直接用 Tokio 有什么不同？Tokio 基于轮询，在 Windows 上还依赖未公开的 API；而 compio 从零开始围绕基于完成的 IO（IOCP/io_uring）构建，并不建立在 tokio 或 mio 之上。
compio 面向谁？和某些同类方案不同，它跨平台吗？它面向构建高性能异步网络/文件系统应用的 Rust 开发者，他们想要一个真正跨平台的基于完成的运行时；与 Monoio（专注 Linux/io_uring）或 Glommio（不支持 Windows）不同，compio 可以在 Linux、Windows 和 macOS 上运行。
它为什么叫 compio？这个名字来自「基于完成的 IO」（completion-based IO），遵循了异步运行时应带「-io」后缀的惯例。
我能调试或检查运行中的 compio 任务吗？可以，启用 console 特性后，compio 会发出可供 tokio-console 消费的 tracing span 和事件，让你观察任务、轮询时长和 waker 活动，包括在 thread-per-core 调度器设置下。
compio 为什么不构建在 tokio 或 mio 之上？Tokio 没有暴露控制 mio 的 API，而 mio 也没有暴露控制 IOCP 的 API，因此 compio 需要自己的基于完成的基础，而不是复用那些抽象。
What are similar projects?libuv, tokio, muduo, swoole-src, hotpath-rs, conc, perry, libevent
Which topics is it in?filesystem, multithreading, runtime, low-level, concurrency, systems-programming, async, observability, networking, performance, rust, library
Creator
compio-rs
Size
3.9 MB
Stars
1.9K
Updated
CommitOct 14Releasev0.19.2Aug 18
Age
3y
Commits · 90 Days