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