docs: add OR_DO_THIS.md zero-dep cancellation pattern#7
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
02df331 to
242718d
Compare
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.
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.
Summary
OR_DO_THIS.md— a one-file, zero-dep cooperative cancellationpattern for crates that can't or won't take the
enoughdep. SameOption<Arc<dyn Fn>>shape asenough::StopToken, closure-backed soany source (
AtomicBool, tokioCancellationToken,enough::Stopper,channels, TLS) bridges in one line.
StopReasonmatchesenough'svariant names so
impl From<StopReason>is portable.tests/test-or-do-this/— a validation crate containing thecopy-pasteable
zerodep.rsfile and 32 unit + 6 doctests that lockin every claim in the document.
StopCheckdeliberately differs fromStopTokentodisambiguate closure-backed vs trait-backed representations when
both crates are in scope.
StopReasondeliberately matches soerror-type impls port without churn.
What's validated
none(),new(),from_flag(),check()?,Clone,Send + Sync, const-ness,core::error::Error.Decoder<'a>).enoughuser callsStopCheck-taking lib) viaclosure, with both
from_flagand reason-preservingnewpaths.StopCheckholder callsenough-using lib) viaalmost_enough::FnStop, including a reason-preserving manualStopimpl.Clonepreserved through the full chain both directions, with acompile-time assertion that
FnStop<move-closure capturing StopCheck>is
Clone.CancelledandTimedOut, includingactual timeout firing via
TimeoutExt::with_timeout.Test plan
cargo test -p test-or-do-this— 32 unit + 6 doctests, all passcargo clippy -p test-or-do-this --all-targets -- -D warnings— cleanwindows-11-arm,i686-unknown-linux-gnu)