morph::async::CallbackToken Class Reference

Weak, copyable observer of a CallbackScope — the half a callback captures. More...

#include <callback_scope.hpp>

Public Member Functions
	CallbackToken ()=default
	Constructs an unbound token, permanently CallbackStatus::Expired.
CallbackStatus	status () const noexcept
	Reports whether the issuing scope is alive, stopped, or gone.
bool	active () const noexcept
	Whether a callback gated on this token may run right now.
bool	expired () const noexcept
	Whether the issuing scope generation is gone (destroyed or reset()).
::core::async::StopToken	stopToken () const noexcept
	The stop token of the issuing scope's generation: stop is requested on it when the scope is stopped, reset or destroyed.
template<typename F>
auto	guard (F &&fn) const
	Wraps fn so it runs only while this token is Active.

Detailed Description

Weak, copyable observer of a CallbackScope — the half a callback captures.

A token keeps nothing alive. It answers whether the scope that issued it is still both present and interested, and it can wrap an arbitrary callable so that the callable no-ops once the answer turns negative.

A default-constructed token is permanently CallbackStatus::Expired: gating is fail-closed, so a token that was never bound to a scope suppresses rather than admits. That trades a silently-dropped callback for never dereferencing a freed receiver, which is the trade this whole type exists to make.

Thread safety

Every member is safe to call from any thread, concurrently with the scope's requestStop() / reset() / destruction. What the result is worth across threads is a separate question — see CallbackScope's "Boundary of the guarantee".

Definition at line 62 of file callback_scope.hpp.

Member Function Documentation

status()

CallbackStatus morph::async::CallbackToken::status ( ) const

inlinenodiscardnoexcept

Reports whether the issuing scope is alive, stopped, or gone.

Returns

Active, Stopped or Expired — see CallbackStatus.

Definition at line 69 of file callback_scope.hpp.

active()

bool morph::async::CallbackToken::active ( ) const

inlinenodiscardnoexcept

Whether a callback gated on this token may run right now.

Advisory across threads: true here means "was active at the moment of the check". See CallbackScope's "Boundary of the guarantee".

Returns

true iff status() == CallbackStatus::Active.

Definition at line 82 of file callback_scope.hpp.

expired()

bool morph::async::CallbackToken::expired ( ) const

inlinenodiscardnoexcept

Whether the issuing scope generation is gone (destroyed or reset()).

Cheaper than status() — no strong reference is taken — and unlike active() it does not conflate "gone" with "stopped".

Returns

true iff the issuing generation no longer exists.

Definition at line 89 of file callback_scope.hpp.

stopToken()

::core::async::StopToken morph::async::CallbackToken::stopToken ( ) const

inlinenodiscardnoexcept

The stop token of the issuing scope's generation: stop is requested on it when the scope is stopped, reset or destroyed.

What a Completion attached through this token links its call's stop source to, so stopping the scope stops the call as well as refusing its callbacks. See docs/spec/core/callback_scope.md, "Stopping the calls a scope owns".

Returns

The generation's token, or a token with no stop state once the generation is gone.

Definition at line 100 of file callback_scope.hpp.

guard()

template<typename F>

auto morph::async::CallbackToken::guard ( F && fn ) const

inlinenodiscard

Wraps fn so it runs only while this token is Active.

The returned callable forwards every argument to fn and returns nothing. When the token is not Active at invocation time it does nothing at all — fn is not called. The wrapper holds a copy of the token, never a strong reference, so wrapping a callback cannot keep the receiver's scope alive.

A suppressed callback is destroyed, not leaked: the wrapper (and with it fn and its captures) is released wherever the refused task is discarded — normally on the delivery executor's thread.

Template Parameters

F

Callable type to wrap. Must return void for every argument list it is invoked with; a value-returning callable has no defensible answer for the suppressed case. Rejected by a static_assert in the returned wrapper's body, so it fires when the wrapper is invoked – a wrapper that is created and never called compiles either way.

Parameters

fn	Callable to gate. Moved into the returned wrapper.

Returns

A callable with fn's argument list and a void return.

Definition at line 126 of file callback_scope.hpp.

---

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

• morph/core/callback_scope.hpp