vlink::CancellationToken Class Reference

Lightweight observer of a CancellationSource shared across worker threads. More...

#include <cancellation.h>

Collaboration diagram for vlink::CancellationToken:

Public Member Functions
	CancellationToken () noexcept
	Constructs an invalid token not bound to any source. More...
bool	valid () const noexcept
	Reports whether the token observes a live cancellation source. More...
bool	is_cancellation_requested () const noexcept
	Returns true once the bound source has been cancelled. More...
CancellationRegistration	register_callback (MoveFunction< void()> &&callback) const
	Subscribes a one-shot callback to fire when the source is cancelled. More...
void	throw_if_cancellation_requested () const
	Throws vlink::Exception::OperationCancelled when cancellation has been requested. More...

Friends
class	CancellationSource

Detailed Description

Lightweight observer of a CancellationSource shared across worker threads.

Tokens are cheap to copy and safe to hand to any thread; many tokens may observe the same source concurrently. A default-constructed token is invalid – it never reports cancellation and never accepts callbacks. Workers typically poll is_cancellation_requested at safe points, call throw_if_cancellation_requested at structured points, or install a one-shot callback via register_callback.

Constructor & Destructor Documentation

CancellationToken()

vlink::CancellationToken::CancellationToken ( )

noexcept

Constructs an invalid token not bound to any source.

Member Function Documentation

is_cancellation_requested()

bool vlink::CancellationToken::is_cancellation_requested ( ) const

noexcept

Returns true once the bound source has been cancelled.

Returns

true after the source's request_cancel has succeeded.

register_callback()

CancellationRegistration vlink::CancellationToken::register_callback

(

MoveFunction< void()> &&

callback

)

const

Subscribes a one-shot callback to fire when the source is cancelled.

When cancellation has not yet been requested the callback is stored in the source and fires once on the thread that later calls CancellationSource::request_cancel. When cancellation already happened the callback runs synchronously inside this call and the returned registration is empty. Exceptions escaping the callback are caught and logged via CLOG_E; they never propagate to the registering or cancelling thread.

Parameters

callback

Move-only nullary functor; an empty callback is silently ignored.

Returns

RAII registration for the subscription, or an empty handle when cancellation had already fired or the token / callback was invalid.

throw_if_cancellation_requested()

void vlink::CancellationToken::throw_if_cancellation_requested

(

)

const

Throws vlink::Exception::OperationCancelled when cancellation has been requested.

Exceptions

vlink::Exception::OperationCancelled

if is_cancellation_requested() is true.

valid()

bool vlink::CancellationToken::valid ( ) const

noexcept

Reports whether the token observes a live cancellation source.

Returns

true when the token was minted from a CancellationSource.

Friends And Related Function Documentation

CancellationSource

friend class CancellationSource

friend

---

The documentation for this class was generated from the following file:

• include/vlink/base/cancellation.h