rust-system-event-driven

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rust System Event-Driven Best Practices

Rust事件驱动系统编程最佳实践

Comprehensive best practices guide for event-driven system programming in Rust. Contains 42 rules across 8 categories, prioritized by impact to guide async runtime usage, channel communication, threading, networking, and terminal handling.

这是一份关于Rust事件驱动系统编程的综合性最佳实践指南，包含8个类别共42条规则，按影响优先级排序，指导异步运行时使用、通道通信、线程处理、网络编程和终端操作。

When to Apply

适用场景

Reference these guidelines when:

Building async applications with Tokio or async-std
Implementing network servers or clients
Writing terminal user interfaces (TUIs)
Managing concurrent tasks and shared state
Handling Unix signals and graceful shutdown

在以下场景中可参考本指南：

使用Tokio或async-std构建异步应用
实现网络服务器或客户端
编写终端用户界面（TUI）
管理并发任务与共享状态
处理Unix信号与优雅停机

Rule Categories by Priority

按优先级划分的规则类别


async-
chan-
sync-
net-
term-
sig-
io-
loop-

Priority	Category	Impact	Prefix
1	Async Runtime Patterns	CRITICAL	`async-`
2	Channel Communication	CRITICAL	`chan-`
3	Threading & Synchronization	HIGH	`sync-`
4	Socket & Network I/O	HIGH	`net-`
5	Terminal & TTY Handling	MEDIUM-HIGH	`term-`
6	Signal & Process Control	MEDIUM	`sig-`
7	File I/O Streaming	MEDIUM	`io-`
8	Event Loop Architecture	LOW-MEDIUM	`loop-`


async-
chan-
sync-
net-
term-
sig-
io-
loop-

优先级	类别	影响级别	前缀
1	异步运行时模式	极高	`async-`
2	通道通信	极高	`chan-`
3	线程与同步	高	`sync-`
4	套接字与网络I/O	高	`net-`
5	终端与TTY处理	中高	`term-`
6	信号与进程控制	中	`sig-`
7	文件I/O流	中	`io-`
8	事件循环架构	中低	`loop-`

Quick Reference

快速参考

1. Async Runtime Patterns (CRITICAL)

1. 异步运行时模式（极高）

```
async-spawn-blocking
```
- Use spawn_blocking for CPU-bound work
```
async-select-biased
```
- Use biased select for priority handling
```
async-no-std-block
```
- Avoid std blocking calls in async context
```
async-cancellation-safe
```
- Design cancellation-safe async operations
```
async-task-local
```
- Use task-local storage for request context
```
async-structured-concurrency
```
- Use JoinSet for structured concurrency

```
async-spawn-blocking
```
- 对CPU密集型任务使用spawn_blocking
```
async-select-biased
```
- 使用biased select处理优先级
```
async-no-std-block
```
- 避免在异步上下文中调用标准库阻塞函数
```
async-cancellation-safe
```
- 设计支持取消的异步操作
```
async-task-local
```
- 使用任务本地存储管理请求上下文
```
async-structured-concurrency
```
- 使用JoinSet实现结构化并发

2. Channel Communication (CRITICAL)

2. 通道通信（极高）

```
chan-bounded-backpressure
```
- Use bounded channels for backpressure
```
chan-oneshot-response
```
- Use oneshot channels for request-response
```
chan-broadcast-fanout
```
- Use broadcast channels for fan-out
```
chan-watch-state
```
- Use watch channels for shared state
```
chan-graceful-shutdown
```
- Use channel closure for graceful shutdown

```
chan-bounded-backpressure
```
- 使用有界通道实现背压
```
chan-oneshot-response
```
- 使用一次性通道处理请求-响应模式
```
chan-broadcast-fanout
```
- 使用广播通道实现扇出模式
```
chan-watch-state
```
- 使用watch通道管理共享状态
```
chan-graceful-shutdown
```
- 通过通道关闭实现优雅停机

3. Threading & Synchronization (HIGH)

3. 线程与同步（高）

```
sync-arc-mutex-shared
```
- Use Arc<Mutex> for shared mutable state
```
sync-rwlock-read-heavy
```
- Use RwLock for read-heavy workloads
```
sync-atomic-counters
```
- Use atomics for simple counters and flags
```
sync-avoid-lock-await
```
- Avoid holding std Mutex across await
```
sync-semaphore-limit
```
- Use Semaphore to limit concurrency
```
sync-parking-lot
```
- Use parking_lot for high-contention locks

```
sync-arc-mutex-shared
```
- 使用Arc<Mutex>管理共享可变状态
```
sync-rwlock-read-heavy
```
- 对读密集型工作负载使用RwLock
```
sync-atomic-counters
```
- 使用原子类型实现简单计数器与标志位
```
sync-avoid-lock-await
```
- 避免在await期间持有标准库Mutex
```
sync-semaphore-limit
```
- 使用Semaphore限制并发数
```
sync-parking-lot
```
- 对高竞争场景使用parking_lot锁

4. Socket & Network I/O (HIGH)

4. 套接字与网络I/O（高）

```
net-split-reader-writer
```
- Split sockets into reader and writer halves
```
net-framing-codec
```
- Use framing for message-based protocols
```
net-connection-pool
```
- Use connection pools for repeated connections
```
net-timeout-all-io
```
- Add timeouts to all network operations
```
net-tcp-nodelay
```
- Set TCP_NODELAY for low-latency protocols
```
net-graceful-disconnect
```
- Implement graceful connection shutdown

```
net-split-reader-writer
```
- 将套接字拆分为读取和写入两个独立部分
```
net-framing-codec
```
- 对基于消息的协议使用帧编码
```
net-connection-pool
```
- 对重复连接使用连接池
```
net-timeout-all-io
```
- 为所有网络操作添加超时
```
net-tcp-nodelay
```
- 为低延迟协议设置TCP_NODELAY
```
net-graceful-disconnect
```
- 实现连接的优雅断开

5. Terminal & TTY Handling (MEDIUM-HIGH)

5. 终端与TTY处理（中高）

```
term-raw-mode-restore
```
- Always restore terminal state on exit
```
term-alternate-screen
```
- Use alternate screen for full-screen apps
```
term-async-event-stream
```
- Use async event stream for terminal input
```
term-buffered-output
```
- Buffer terminal output for performance
```
term-handle-resize
```
- Handle terminal resize events

```
term-raw-mode-restore
```
- 程序退出时务必恢复终端状态
```
term-alternate-screen
```
- 对全屏应用使用备用屏幕
```
term-async-event-stream
```
- 使用异步事件流处理终端输入
```
term-buffered-output
```
- 对终端输出使用缓冲以提升性能
```
term-handle-resize
```
- 处理终端窗口大小调整事件

6. Signal & Process Control (MEDIUM)

6. 信号与进程控制（中）

```
sig-ctrl-c-graceful
```
- Handle Ctrl-C for graceful shutdown
```
sig-unix-signals
```
- Handle Unix signals asynchronously
```
sig-child-reap
```
- Reap child processes to avoid zombies
```
sig-timeout-shutdown
```
- Set shutdown timeout to force exit

```
sig-ctrl-c-graceful
```
- 处理Ctrl-C信号以实现优雅停机
```
sig-unix-signals
```
- 异步处理Unix信号
```
sig-child-reap
```
- 回收子进程以避免僵尸进程
```
sig-timeout-shutdown
```
- 设置停机超时以强制退出

7. File I/O Streaming (MEDIUM)

7. 文件I/O流（中）

```
io-async-file-ops
```
- Use async file operations in async context
```
io-stream-large-files
```
- Stream large files instead of loading entirely
```
io-copy-bidirectional
```
- Use copy_bidirectional for proxying
```
io-pipe-communication
```
- Use pipes for process communication
```
io-flush-before-read
```
- Flush writes before expecting responses

```
io-async-file-ops
```
- 在异步上下文中使用异步文件操作
```
io-stream-large-files
```
- 流式处理大文件而非一次性加载
```
io-copy-bidirectional
```
- 使用copy_bidirectional实现代理
```
io-pipe-communication
```
- 使用管道实现进程间通信
```
io-flush-before-read
```
- 读取响应前先刷新写入操作

8. Event Loop Architecture (LOW-MEDIUM)

8. 事件循环架构（中低）

```
loop-actor-model
```
- Use actor pattern for stateful components
```
loop-event-types
```
- Use typed events over dynamic dispatch
```
loop-state-machine
```
- Model protocol state as type-safe state machine
```
loop-layered-architecture
```
- Separate I/O from business logic
```
loop-cancellation-token
```
- Use CancellationToken for coordinated shutdown

```
loop-actor-model
```
- 对有状态组件使用Actor模式
```
loop-event-types
```
- 使用类型化事件替代动态分发
```
loop-state-machine
```
- 将协议状态建模为类型安全的状态机
```
loop-layered-architecture
```
- 将I/O层与业务逻辑分离
```
loop-cancellation-token
```
- 使用CancellationToken实现协同停机

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明与代码示例：

章节定义 - 类别结构与影响级别说明
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	类别定义与排序说明
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息