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

async-

chan-

sync-

net-

term-

sig-

io-

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