commit 8dfa7726ec4b30498110e1563ca653eafee24bfb
parent 969b31513131bd7790a8b5c1b528433b3bb13ac7
Author: alltheseas <alltheseas@users.noreply.github.com>
Date: Fri, 2 Jan 2026 17:32:16 -0600
docs: update Async & Background Work section
Clarify the async patterns used in the codebase:
- Emphasize poll_promise::Promise as the dominant pattern
- Clarify JobPool is for CPU-bound work (blurhash, etc.)
- Document tokio::spawn and JoinSet for network I/O
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Diffstat:
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -55,7 +55,9 @@ This document captures the current architecture, coding conventions, and design
### Async & Background Work
-- **`JobPool`** (`crates/notedeck/src/job_pool.rs`) provides a lightweight thread pool returning Futures via `tokio::sync::oneshot`, useful for CPU-bound tasks without blocking the UI.
+- **Promise-based async** (`poll_promise::Promise`): The dominant pattern for async work. Promises are polled via `promise.ready()` in the render loop—never blocking. Results are consumed when available.
+- **`JobPool`** (`crates/notedeck/src/job_pool.rs`): A 2-thread pool for CPU-bound work (e.g., blurhash computation). Returns results via `tokio::sync::oneshot` wrapped in Promises.
+- **Tokio tasks**: Network I/O, wallet operations, and relay sync use `tokio::spawn()`. Use `tokio::task::JoinSet` when managing multiple concurrent tasks.
- **Dave async**: Streams AI tokens through channels, spawns tasks with `tokio::spawn`, and updates the UI as chunks arrive—see `crates/notedeck_dave/src/lib.rs`.
- **Relay events**: Columns polls `RelayPool::try_recv()` inside the egui loop, translates network activity into timeline mutations, and schedules follow-up fetches (e.g., `timeline::poll_notes_into_view`).
