rust-system-event-driven

Rust System Event-Driven Best Practices

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.

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

Rule Categories by Priority

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-

Quick Reference

1. Async Runtime Patterns (CRITICAL)

• 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

2. Channel Communication (CRITICAL)

• 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

3. Threading & Synchronization (HIGH)

• sync-arc-mutex-shared - Use Arc 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

4. Socket & Network I/O (HIGH)

• 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

5. Terminal & TTY Handling (MEDIUM-HIGH)

• 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

6. Signal & Process Control (MEDIUM)

• 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

7. File I/O Streaming (MEDIUM)

• 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

8. Event Loop Architecture (LOW-MEDIUM)

• 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

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