docs(daemon): document task ownership at fire-and-forget spawn sites#305
Merged
Conversation
Phase 10c hand-audit of all 18 prod `tokio::spawn(` sites (27 raw
audit-script matches \u2212 9 in-file test-mod matches) found that 16
of 18 already have explicit task-ownership semantics via either a
named `spawn_*` constructor with rustdoc or inline comments
answering all four required facets (owner, shutdown, error obs.,
cancel behavior).
Two sites lacked an explicit `# Task ownership` block:
* `crates/uffs-daemon/src/handler.rs:510` (`handle_refresh`) \u2014
fire-and-forget RPC handler whose previous one-line rustdoc
didn't explain that the spawned task is intentionally
detached, runs to completion regardless of daemon shutdown,
and has no upward error propagation (the immediate ack only
asserts scheduling, not refresh success).
* `crates/uffs-daemon/src/lib.rs:697` (Windows named-pipe IPC
spawn) \u2014 inline spawn inside `spawn_ipc_servers` whose
asymmetric ownership (AF_UNIX held + `.abort()`-ed; named-pipe
fire-and-forget) wasn't called out next to the call-site.
Both additions are documentation-only \u2014 zero behavior change,
zero source-line changes beyond rustdoc + inline comment blocks.
Full per-site inventory in
`docs/dev/baseline/2026-05-19/phase_10_task_ownership_inventory.md`
(local; gitignored).
## Rule-1 adherence
* Zero `#[allow(...)]` introductions.
* No suppression hacks, no skipped tests.
* Surgical \u2014 minimum text needed to enumerate the four required
facets at each site.
* `cargo check -p uffs-daemon` clean.
* `cargo clippy -p uffs-daemon --all-targets -- -D warnings` clean.
* `cargo test -p uffs-daemon --lib` \u2014 298 passed / 0 failed.
Refs #302.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Phase 10c task-ownership inventory closure. Hand-audit of all 18 prod
tokio::spawn(sites found 16 already textbook-clean (namedspawn_*constructor with rustdoc, OR inline comments answering all four required facets: owner / shutdown / error obs. / cancel behavior). This PR fills in the remaining 2 gaps with minimal# Task ownershiprustdoc additions.Why
Phase 10 acceptance criterion #2 (playbook §1142) requires that every
tokio::spawn(call-site has, at the call-site or enclosing named-spawner function, a comment / rustdoc block answering "who owns / how it's shut down / how errors are observed / what happens on cancellation."Per-site inventory (all 18 prod sites with full verdicts) lives in
docs/dev/baseline/2026-05-19/phase_10_task_ownership_inventory.md(local-only;docs/dev/baseline/is gitignored).Sites augmented in this PR
crates/uffs-daemon/src/handler.rs:510(handle_refresh)Previously a one-line rustdoc: "spawns refresh in background, returns immediate ack."
That didn't explain:
JoinHandleis discarded; the closure capturesArc<IndexManager>to keep the manager alive.process::exitis the only termination mechanism.statusfor completion.Added a full
# Task ownershipblock enumerating those.crates/uffs-daemon/src/lib.rs:697(Windows named-pipe IPC spawn)Inline spawn inside
spawn_ipc_serverswhose asymmetric ownership wasn't called out next to the call-site:.abort()-ed during graceful shutdown._pipe_taskbinding drops at end-of-scope; the task itself outlives via Tokio's auto-detach.Added a
// Task ownership (Phase 10c):block explaining the deliberate asymmetry.Rule-1 adherence
#[allow(...)]introductions.Verification
Local:
cargo check -p uffs-daemon\u2014 clean.cargo clippy -p uffs-daemon --all-targets -- -D warnings\u2014 0 warnings.cargo test -p uffs-daemon --lib\u2014 298 passed / 0 failed.scripts/hooks/_lint_fast.sh(pre-commit) \u2014 all 7 stages passed.scripts/hooks/_lint_pre_push.sh\u2014 all 17 stages passed in 83s.Acceptance against playbook §1142-1146 (Phase 10 §2)
\u2705 CLOSED for Phase 10c. All 18 prod
tokio::spawn(sites now have, at the call-site or enclosing named-spawner function, a comment / rustdoc block answering the four required facets. Inventory will be folded intoconcurrency_policy.md §'Spawn-site registry'in Phase 10g.Tracking
Refs #302 (Phase 10 umbrella). Follow-on PRs:
std::fs::*insideasync fnoutsidespawn_blocking.concurrency_policy.md+ per-crate# Concurrencyrustdoc.