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

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<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

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