Skip to content

docs: add OR_DO_THIS.md zero-dep cancellation pattern#7

Merged
lilith merged 1 commit intomainfrom
docs/or-do-this
Apr 9, 2026
Merged

docs: add OR_DO_THIS.md zero-dep cancellation pattern#7
lilith merged 1 commit intomainfrom
docs/or-do-this

Conversation

@lilith
Copy link
Copy Markdown
Member

@lilith lilith commented Apr 8, 2026

Summary

  • Adds OR_DO_THIS.md — a one-file, zero-dep cooperative cancellation
    pattern for crates that can't or won't take the enough dep. Same
    Option<Arc<dyn Fn>> shape as enough::StopToken, closure-backed so
    any source (AtomicBool, tokio CancellationToken, enough::Stopper,
    channels, TLS) bridges in one line. StopReason matches enough's
    variant names so impl From<StopReason> is portable.
  • Adds tests/test-or-do-this/ — a validation crate containing the
    copy-pasteable zerodep.rs file and 32 unit + 6 doctests that lock
    in every claim in the document.
  • Naming note: StopCheck deliberately differs from StopToken to
    disambiguate closure-backed vs trait-backed representations when
    both crates are in scope. StopReason deliberately matches so
    error-type impls port without churn.

What's validated

  • Standalone use — none(), new(), from_flag(), check()?,
    Clone, Send + Sync, const-ness, core::error::Error.
  • Storage without lifetime parameters (no viral Decoder<'a>).
  • Forward adapter (enough user calls StopCheck-taking lib) via
    closure, with both from_flag and reason-preserving new paths.
  • Reverse adapter (StopCheck holder calls enough-using lib) via
    almost_enough::FnStop, including a reason-preserving manual
    Stop impl.
  • Clone preserved through the full chain both directions, with a
    compile-time assertion that FnStop<move-closure capturing StopCheck>
    is Clone.
  • Reason preservation for both Cancelled and TimedOut, including
    actual timeout firing via TimeoutExt::with_timeout.

Test plan

  • cargo test -p test-or-do-this — 32 unit + 6 doctests, all pass
  • cargo clippy -p test-or-do-this --all-targets -- -D warnings — clean
  • CI green across all platforms (Linux, macOS Intel, macOS aarch64, Windows, windows-11-arm, i686-unknown-linux-gnu)

@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Apr 8, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.85%. Comparing base (8f1dbc3) to head (f398ddf).

Additional details and impacted files
@@           Coverage Diff           @@
##             main       #7   +/-   ##
=======================================
  Coverage   97.85%   97.85%           
=======================================
  Files          16       16           
  Lines        2336     2336           
=======================================
  Hits         2286     2286           
  Misses         50       50           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@lilith lilith force-pushed the docs/or-do-this branch 7 times, most recently from 02df331 to 242718d Compare April 9, 2026 09:00
One-file StopCheck pattern for crates that can't or won't take the
enough dep. Same Option<Arc<dyn Fn>> shape as enough::StopToken,
closure-backed so any cancellation source (AtomicBool, tokio
CancellationToken, enough::Stopper, channels) bridges in one line.

StopReason matches enough's variant names so `impl From<StopReason>`
is portable between the two. StopCheck is deliberately named
differently from StopToken to disambiguate the closure-backed vs
trait-backed representations when both are in scope.

Validated by the new tests/test-or-do-this crate: 32 unit + 6
doctests covering standalone use, struct storage without lifetime
parameters, bidirectional enough interop (forward adapter via
closure, reverse adapter via FnStop), Clone preservation through
the full chain including FnStop<move-closure>: Clone, reason-
preserving bridges for both Cancelled and TimedOut (including
actual timeout firing), and core::error::Error impl.
@lilith lilith force-pushed the docs/or-do-this branch from 242718d to f398ddf Compare April 9, 2026 09:30
@lilith lilith merged commit 9e8f2e1 into main Apr 9, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants