NethermindEth / NethermindEth/pluto

Define and enforce `CancellationToken` conventions

Open
#614 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation rust
Dominant language
Rust
Stars
8
Forks
5
Avg merge
4d 16h
Merged PRs (30d)
37

Description

Summary

CancellationToken is the most pervasive abstraction in the workspace (550 lines across 74 files) with no written rules, and usage has drifted:

  • clone() vs child_token() is ~141:52. A clone shares the same scope, so any holder calling .cancel() tears down the whole tree; children are the right default for subordinate tasks. Disciplined child_token use exists only in dkg; large subsystems (tracker: 19 CT lines, validatorapi: 25, sse: 15) use zero.
  • drop_guard() appears exactly twice (privkeylock.rs#L123, wire.rs#L1140). Everywhere else an early-returning task leaves siblings running with no signal.
  • Orphan tokens with no parent link (cancel never propagates from the caller): prioritiser's quit, deadliner's internal token, dkg's lock_ct.
  • Three vocabularies coexist: select! { _ = ct.cancelled() => ... } (~41 sites), ct.run_until_cancelled(fut) (24 sites, nearly all in one file), and the third-party cancellation crate's callback API in the QBFT core (goes away with draft 05a).
  • Naming (ct, cancel, cancellation, token, quit) and by-value vs &CancellationToken passing are unstandardized, forcing gratuitous clones at boundaries.

Proposed change

Update the current set of conventions: when to child_token vs clone, when a task owns a DropGuard, one preferred waiting idiom, parameter naming and passing. Then sweep the flagged sites — in particular giving subordinate tasks child tokens and auditing the orphan tokens for missed shutdown propagation.

Acceptance

Documented rules plus a pass over tracker/validatorapi/sse/prioritiser aligning them; no orphan token without a comment explaining its independence.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading .claude/skills/rust-style/SKILL.md and reviewing the existing CancellationToken usage in tracker, validatorapi, sse, and prioritiser. Compare the linked drop_guard sites in privkeylock.rs and wire.rs with the orphan-token cases, then document the conventions and align the flagged sites. Done means the acceptance criteria are met, including comments for any intentionally independent orphan tokens.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
distributed-systems
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.