# pyraio

**Repository Path**: leongle/pyraio

## Basic Information

- **Project Name**: pyraio
- **Description**: 基于rust和pyo3实现的异步io通信库，可以配合ayncio使用
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pyraio

> **PyO3 0.29 + tokio 1 异步运行时桥接演示** · v0.5
>
> 重命名自 `demo`（v0.4 及以前）。**v0.8 起 Rust crate、Python package、wheel name 全部统一为 `pyraio`**。内部 Rust module 叫 `_pyraio_native`，用户 `import pyraio`，wheel 文件名 `pyraio-0.2.0-...whl`，`pip install pyraio`。

## 6 种集成模式

| 模式 | API | 适用场景 |
|------|-----|----------|
| M1 同步 | `pyraio.call_sync(id)` | <10ms 短任务、启动初始化 |
| **M2 异步** | `await pyraio.call_async(id)` | **默认 95% 场景** |
| M2.1 同步 Rust 桥接 | `await pyraio.call_blocking(id)` | 异步主循环 + 同步阻塞库 |
| M2.2 CPU 密集 | `await pyraio.heavy_compute(n)` | 不阻塞 event loop 的纯计算 |
| M2.3 多 worker | `await pyraio.call_async_with_workers(w, id)` | 隔离 runtime / 调 worker 数 |
| M3 流式 | `async for ev in pyraio.subscribe(): ...` | WebSocket / SSE / 消息订阅 |

## 一键复现（推荐）

```bash
cd /workspace/demo
./run.sh
```

输出：

```
==> checking rust toolchain
✓ rust 1.97.0
==> building wheel (maturin build --release)
✓ wheel: pyraio-0.2.0-cp311-cp311-manylinux_2_34_x86_64.whl
==> smoke test (one call of each mode)
smoke OK
==> running pytest tests/
============================== 17 passed in 2.34s ==============================
==> running bench.py
mode                                               value
------------------------------------------------------------
M1 baseline                                     6.7 RPS  (c=1, n=200)
M1 PyO3 sync                                    6.6 RPS  (c=1, n=200)
M2 async c=100                                644.0 RPS  (c=100, n=200)
M2.1 sync-bridge c=100                        633.4 RPS  (c=100, n=200)
M2.2 CPU-bound c=100                        16063.8 RPS  (c=100, n=200)
M2.3 multi-worker w=1                         151.6 ms  (p99=152.0ms)
M2.3 multi-worker w=2                         151.7 ms  (p99=162.6ms)
M2.3 multi-worker w=4                         151.7 ms  (p99=151.7ms)
M3 streaming                                    9.9 events/s
progress_stream                              2.5600 s
```

子命令：`./run.sh tests` / `./run.sh bench` / `./run.sh web`。

## 看压测页面

```bash
cd /workspace/demo/web && python3 -m http.server 8000
# 浏览器开 http://localhost:8000
```

或直接：`./run.sh web`。

## 手动步骤

如果 `./run.sh` 不适合你的环境：

```bash
. "$HOME/.cargo/env"            # cargo
. .venv/bin/activate             # venv
maturin build --release
pip install --force-reinstall target/wheels/pyraio-0.2.0-cp311-cp311-manylinux_2_34_x86_64.whl
PYTHONPATH=. pytest tests/ -v   # 17/17
PYTHONPATH=. python3 bench.py   # 压测
```

## 关键数据

| 模式 | RPS | 加速比 vs M1 baseline |
|------|-----|---------------------|
| M1 baseline (Python sync) | 6.7 | 1.0x |
| M1 pyraio sync | 6.6 | 1.0x |
| **M2 async (c=100)** | **640** | **95.4x** |
| M2.1 sync-bridge | 646 | 96.4x |
| M2.2 CPU-bound | 15,482 | 2,310x |
| M3 streaming | 9.9 ev/s | (流式) |

**TL;DR**：150ms 模拟后端下，PyO3 async 比 Python sync 快 **97x**。

## v0.4 → v0.5 关键变更

1. **全栈重命名**（v0.8）：`demo` → `pyraio`（crate / wheel / Python import 全部统一）
2. **PyO3 0.29 Bound API**：gil-refs 移除，所有 `&PyAny` → `Bound<'_, PyAny>`
3. **Python::with_gil/allow_threads 移除**：`call_sync` 改用独立 OS 线程 + `std::sync::mpsc::channel`
4. **init_with_runtime 新 API**：可选 `(runtime: &'static Runtime)`，默认仍用 `init(builder)`
5. **shutdown idempotent**：`AtomicBool` flag 防止多次调触发 double-free
6. **Gil-refs 完全删除**：`m.py().get_type::<T>()` 仍 work（pyo3 0.29 Bound API 默认）

详见 `/workspace/spec/pyo3-tokio-asyncio-spec-v0.5.md`。

## 项目结构

```
pyraio/                              # wheel package name = "pyraio"（import 统一）
├── Cargo.toml                       # crate name = "pyraio", lib name = "pyraio"
├── pyproject.toml                   # module-name = "_pyraio_native"
├── src/lib.rs                       # 主实现（6 模式 + EventStream + MyBackendError）
├── tests/test_demo.py               # 32 个测试（保留文件名兼容 pytest discovery）
├── bench.py                         # 6 模式压测
├── (无 demo 兼容 shim, 直接 import pyraio)
├── run.sh                           # 一键复现脚本
├── web/
│   └── index.html                   # 公开压测页面
├── BENCH_REPORT.md                  # 压测数据
└── README.md                        # 本文件
```

## Spec

完整 spec：`/workspace/spec/pyo3-tokio-asyncio-spec-v0.5.md`（14KB）。