Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Concurrency & Locking Standards

Runtime model: one UI thread (egui), one Tokio runtime owned by CoreEngine (src/core/), blocking work on spawn_blocking, SQLite accessed via CoreEngine/spawn_blocking.


1. Thread Ownership Matrix

ResourceOwnerAccess rule
UI state (egui context, widget state)UI threadNever mutated off-thread.
Tokio runtime, HTTP client, WebSocketWorkerUI only sends WorkerCmd.
SQLite MessageStoreWorkerOne connection, no cross-thread sharing.
session.json / SessionWorkerUI receives snapshots, not handles.
Media/sticker cachesWorker (write), UI (read snapshot)No shared &mut.

INV-3: the UI thread never blocks on network, disk, crypto or SQLite.


2. Channel Rules

ChannelTypeDirectionRule
Commandstokio::sync::mpsc::UnboundedSender<WorkerCmd>UI → WorkerOne variant per user intent; no generic escape hatch.
Eventsstd::sync::mpsc (UI polled via try_recv)Worker → UITerminal event required for every fallible command.
WebSocketTokio taskWorker internalRead loop never blocks on decoding.
  • Sending must never block the UI; use send/try_send appropriately and handle a closed channel.
  • A producer that can flood must rate-limit at the source (polling cadence, coalescing) rather than buffering unboundedly.
  • Dropping the receiver must not panic the worker; log and shut down cleanly.

3. Blocking Work

  • spawn_blocking for: SQLite, image decode, ZIP/sticker unpack, file hashing.
  • Never call block_on inside async context.
  • Never hold a MutexGuard across .await.
  • File and DB handles stay inside the blocking closure.

4. Shared State

TierMechanismWhen
Tier 1 — message passingmpsc channelsDefault. Prefer over shared state.
Tier 2 — single-writerworker-owned structMutable state only the worker touches.
Tier 3 — shared readArc<T> immutable snapshotUI needs data the worker produced.
Tier 4 — lockstd::sync::Mutex / RwLock (short critical sections)Rare, and only when tiers 1–3 do not fit.

If a lock is unavoidable:

  • Document why in a Tier 2 comment.
  • Keep the critical section free of I/O, logging and allocation-heavy work.
  • Never acquire a second lock while holding one unless an ordering rule is documented.

5. Lock Ordering & Deadlock Prevention

When multiple resources must be locked:

  1. Define a global order once (e.g. session → store → cache).
  2. Acquire in that order everywhere; never invert.
  3. Prefer try-lock with timeout over indefinite blocking on user-visible paths.
  4. If ordering cannot be guaranteed, restructure to message passing instead of adding a lock.

6. Failure Policy

OperationPolicyRationale
UI refreshFail-openStale view beats a frozen window.
Message sendFail-closedNever show “sent” when the server rejected it.
History writeFail-openLocal cache loss must not drop a message.
Session/authFail-closedNever continue with an expired credential.

7. Timeouts & Cancellation

  • Every network await has a timeout; no unbounded await.
  • Long operations check a cancellation token / channel-closed state between units of work.
  • On app shutdown: signal cancellation, drain the command channel, join with a bounded wait, then exit.
  • Background tasks that outlive their owner are a leak — tie them to the worker lifetime.

8. Race Checklist

  • No shared mutable state without a documented owner.
  • No .await while holding a lock.
  • No block_on in async code; no blocking call on the UI thread.
  • Every channel send handles a closed receiver.
  • Every spawned task has an owner and a termination path.
  • Polling loops have a fixed cadence and cannot overlap themselves.