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