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