cancellation.h File Reference

Cooperative one-shot cancellation primitives shared by VLink async building blocks. More...

#include <cstddef>
#include <memory>
#include "./functional.h"
#include "./macros.h"

Include dependency graph for cancellation.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	vlink::CancellationRegistration
	Move-only RAII handle that represents one subscribed cancellation callback. More...
class	vlink::CancellationToken
	Lightweight observer of a CancellationSource shared across worker threads. More...
class	vlink::CancellationSource
	Mutator that mints observer tokens and signals one-shot cancellation. More...

Namespaces
	vlink

Detailed Description

Cooperative one-shot cancellation primitives shared by VLink async building blocks.

Cancellation is split into a writable CancellationSource owned by the work producer, one or more read-only CancellationToken observers held by workers, and per-callback CancellationRegistration handles used to unsubscribe pending callbacks. All three share a refcounted internal state allocated on the producer side.

Role table

Type	Role	Copy / Move
CancellationSource	Mutator; signals cancellation	Implicit (refcount)
CancellationToken	Observer; poll / throw / subscribe	Copyable
CancellationRegistration	RAII slot for one subscribed callback	Move-only

State diagram

*   +------------+   request_cancel()    +---------------+   no-ops on further calls
*   |  active    | --------------------> |  cancelled    | -------------------------+
*   |  (default) |                       |  (terminal)   |                          |
*   +------------+                       +---------------+                          |
*      ^   ^                                ^                                       |
*      |   |  is_cancellation_requested()=false                                     |
*      |   |  throw_if_cancellation_requested()=no-op                               |
*      |   |                                                                        v
*      |   +-- new tokens via token() share the same state ------------------ read-only
*      |
*      +------ register_callback() inserts a slot; fires synchronously on transition
* 

Cancellation is one-shot. After the first successful request_cancel the state is terminal; subsequent requests return false and never re-invoke callbacks. The cancelled type re-exported as vlink::Exception::OperationCancelled is the canonical thrown type at structured cancellation points.

Lock ordering

Internal mutexes are released before user callbacks fire, so callbacks may freely cancel sibling sources or register more callbacks without self-deadlock.

Example

vlink::CancellationSource source;
auto token = source.token();
 
auto reg = token.register_callback([] {
  // Runs once on the cancelling thread, or inline if already cancelled.
});
 
while (!token.is_cancellation_requested()) {
  token.throw_if_cancellation_requested();
  run_work_unit();
}
 
source.request_cancel();