pub struct ForegroundCancel { /* private fields */ }Expand description
The armed foreground token, shared between the host (which cancels) and every subsystem that spawns cancellable work (which arms).
Mutex rather than ArcSwap because arming is a compare-and-swap
in spirit — cancel the old, install the new — and it happens once
per user-initiated operation, not per keystroke or per frame. There
is no hot-path read: the token is what gets polled in tight loops,
and that is a plain atomic the caller already holds by then.
Implementations§
Source§impl ForegroundCancel
impl ForegroundCancel
Sourcepub fn current_token(&self) -> Option<CancellationToken>
pub fn current_token(&self) -> Option<CancellationToken>
A clone of the currently-armed token, if any (CG.4).
For callers that must poll cancellation from a context the arming caller never reached — the plugin host’s epoch callback, which fires every millisecond inside a running guest call and cannot take a lock there. It takes the lock ONCE per guest call and polls the returned token (a plain atomic) thereafter, which is the split this module’s own docs describe: “the token is what gets polled in tight loops”.
None when nothing is armed — no foreground operation is
running, so there is nothing for the caller to be cancelled by.
Sourcepub fn arm(&self) -> CancellationToken
pub fn arm(&self) -> CancellationToken
Arm a fresh token for a user-initiated operation, cancelling any predecessor, and hand back the clone the spawned task holds.
Takes &self on purpose: the callers that need it most are
action-handler closures and event subscriptions, which never see
&mut Editor.
A poisoned lock is treated as “nothing was armed” rather than a panic — losing the ability to cancel one operation is a far smaller failure than taking the editor down, and the fresh token this returns is still valid for the caller about to spawn.
Sourcepub fn enrol(&self, token: CancellationToken)
pub fn enrol(&self, token: CancellationToken)
Join the foreground set without superseding anything (CG.3).
For work that already has its own cancellation discipline and
only needs <C-g> to reach it. Every user-triggered LSP command
is like this: hover, rename, format and code-actions each hold a
per-feature token so a second hover supersedes the first, and
that is the right granularity — a hover has no business
cancelling a rename.
arm would be wrong here. K is a reflexive
inspect key; making it supersede would mean glancing at a symbol
silently kills the project search you are waiting on, with a
half-populated buffer and nothing to say why.
Automatic requests must not come through here at all —
completion, signature-help and the maybe_request_* family fire
on keystrokes, cursor moves and ticks. They are not
user-triggered, so by §3 of the design they are not foreground;
enrolling them would make <C-g> cancel whatever the editor
happened to be doing on its own behalf.
Already-cancelled entries are pruned on each call, which is what
keeps the set from growing without bound across a session: a
completed request’s token is never cancelled, so pruning cannot
rely on it — instead the set is small by construction (one live
request per feature) and every cancel() empties it.
Sourcepub fn cancel(&self)
pub fn cancel(&self)
Cancel everything foreground: the armed slot and every enrolled token. Clears both.
Idempotent — cancelling nothing is the common case, since the binding is pressed far more often than an operation is running.
Sourcepub fn enrolled_len(&self) -> usize
pub fn enrolled_len(&self) -> usize
How many tokens are currently enrolled. For tests and for a
future status indicator (cancellation.md §7).