Tokio Async Code Review

Review Workflow

1. Check Cargo.toml — Note tokio feature flags (

   full

   ,

   rt-multi-thread

   ,

   macros

   ,

   sync

   , etc.). Missing features cause confusing compile errors.
2. Check runtime setup — Is

   #[tokio::main]

   or manual runtime construction used? Multi-thread vs current-thread?
3. Scan for blocking — Search for

   std::fs

   ,

   std::net

   ,

   std::thread::sleep

   , CPU-heavy loops in async functions.
4. Check channel usage — Match channel type to communication pattern (mpsc, broadcast, oneshot, watch).
5. Check sync primitives — Verify correct mutex type, proper guard lifetimes, no deadlock potential.

Output Format

Report findings as:

[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
Description of the issue and why it matters.

Quick Reference

Issue Type	Reference
Task spawning, JoinHandle, structured concurrency	references/task-management.md
Mutex, RwLock, Semaphore, Notify, Barrier	references/sync-primitives.md
mpsc, broadcast, oneshot, watch channel patterns	references/channels.md

Review Checklist

Runtime Configuration

• Tokio features in Cargo.toml match actual usage
• Runtime flavor matches workload (

  multi_thread

  for I/O-bound,

  current_thread

  for simpler cases)

• #[tokio::test]

  used for async tests (not manual runtime construction)
• Worker thread count configured appropriately for production

Task Management

• spawn

  return values (

  JoinHandle

  ) are tracked, not silently dropped

• spawn_blocking

  used for CPU-heavy or synchronous I/O operations
• Tasks respect cancellation (via

  CancellationToken

  ,

  select!

  , or shutdown channels)

• JoinError

  (task panic or cancellation) is handled, not just unwrapped

• tokio::select!

  branches are cancellation-safe

Sync Primitives

• tokio::sync::Mutex

  used when lock is held across

  .await

  ;

  std::sync::Mutex

  for short non-async sections
• No mutex guard held across await points (deadlock risk)

• Semaphore

  used for limiting concurrent operations (not ad-hoc counters)

• RwLock

  used when read-heavy workload (many readers, infrequent writes)

• Notify

  used for simple signaling (not channel overhead)

Channels

• Channel type matches pattern: mpsc for back-pressure, broadcast for fan-out, oneshot for request-response, watch for latest-value
• Bounded channels have appropriate capacity (not too small = deadlock, not too large = memory)

• SendError

  /

  RecvError

  handled (indicates other side dropped)
• Broadcast

  Lagged

  errors handled (receiver fell behind)
• Channel senders dropped when done to signal completion to receivers

Timer and Sleep

• tokio::time::sleep

  used instead of

  std::thread::sleep

• tokio::time::timeout

  wraps operations that could hang

• tokio::time::interval

  used correctly (

  .tick().await

  for periodic work)

Severity Calibration

Critical

• Blocking I/O (

  std::fs::read

  ,

  std::net::TcpStream

  ) in async context without

  spawn_blocking

• Mutex guard held across

  .await

  point (deadlock potential)

• std::thread::sleep

  in async function (blocks runtime thread)
• Unbounded channel where back-pressure is needed (OOM risk)

Major

• JoinHandle

  silently dropped (lost errors, zombie tasks)
• Missing

  select!

  cancellation safety consideration
• Wrong mutex type (std vs tokio) for the use case
• Missing timeout on network/external operations

Minor

• tokio::spawn

  for trivially small async blocks (overhead > benefit)
• Overly large channel buffer without justification
• Manual runtime construction where

  #[tokio::main]

  suffices

• std::sync::Mutex

  where contention is high enough to benefit from tokio's async mutex

Informational

• Suggestions to use

  tokio-util

  utilities (e.g.,

  CancellationToken

  )
• Tower middleware patterns for service composition
• Structured concurrency with

  JoinSet

Valid Patterns (Do NOT Flag)

• std::sync::Mutex

  for short critical sections — tokio docs recommend this when no

  .await

  is inside the lock

• tokio::spawn

  without explicit join — Valid for background tasks with proper shutdown signaling
• Unbuffered channel capacity of 1 — Valid for synchronization barriers

• #[tokio::main(flavor = "current_thread")]

  in simple binaries — Not every app needs multi-thread runtime

• clone()

  on

  Arc<T>

  before

  spawn

  — Required for moving into tasks, not unnecessary cloning
• Large broadcast channel capacity — Valid when lagged errors are expensive (event sourcing)

Before Submitting Findings

Load and follow

beagle-rust:review-verification-protocol

before reporting any issue.