pulp::runtime::AliveToken Class Reference

Shared, fail-closed lifetime signal for callbacks that may outlive an owner. More...

#include <alive_token.hpp>

Classes
class	Lease
	A temporary lease proving that an owner-backed callback may safely use its referenced state. More...

Public Types
using	Handle = std::shared_ptr<State>

Public Member Functions
	AliveToken ()
	~AliveToken ()
	AliveToken (const AliveToken &)=delete
AliveToken &	operator= (const AliveToken &)=delete
	AliveToken (AliveToken &&)=delete
AliveToken &	operator= (AliveToken &&)=delete
Handle	capture () const noexcept
void	retire () noexcept
	Retire from the owner teardown context, outside any callback that holds a Lease.
void	reset ()

Static Public Member Functions
static bool	is_alive (const Handle &handle) noexcept
static bool	is_alive (const std::shared_ptr< std::atomic< bool > > &handle) noexcept
static Lease	try_acquire (const Handle &handle) noexcept
	Atomically admit one callback before teardown can retire the owner.

Detailed Description

Shared, fail-closed lifetime signal for callbacks that may outlive an owner.

The owner keeps the AliveToken and callbacks capture a Handle. Destroying or explicitly retiring the token flips every handle to false and waits for leases held by in-flight callbacks before the owner's referenced state is released. A handle never extends the owner's lifetime; it only makes the decision to avoid dereferencing it safe.

Member Typedef Documentation

Handle

using pulp::runtime::AliveToken::Handle = std::shared_ptr<State>

Constructor & Destructor Documentation

AliveToken() [1/3]

pulp::runtime::AliveToken::AliveToken ( )

inline

~AliveToken()

pulp::runtime::AliveToken::~AliveToken ( )

inline

AliveToken() [2/3]

pulp::runtime::AliveToken::AliveToken ( const AliveToken & )

delete

AliveToken() [3/3]

pulp::runtime::AliveToken::AliveToken ( AliveToken && )

delete

Member Function Documentation

capture()

Handle pulp::runtime::AliveToken::capture ( ) const

inlinenoexcept

is_alive() [1/2]

bool pulp::runtime::AliveToken::is_alive ( const Handle & handle )

inlinestaticnoexcept

is_alive() [2/2]

bool pulp::runtime::AliveToken::is_alive ( const std::shared_ptr< std::atomic< bool > > & handle )

inlinestaticnoexcept

operator=() [1/2]

AliveToken & pulp::runtime::AliveToken::operator= ( AliveToken && )

delete

operator=() [2/2]

AliveToken & pulp::runtime::AliveToken::operator= ( const AliveToken & )

delete

reset()

void pulp::runtime::AliveToken::reset ( )

inline

retire()

void pulp::runtime::AliveToken::retire ( )

inlinenoexcept

Retire from the owner teardown context, outside any callback that holds a Lease.

A reentrant retire on the leased callback thread waits for that callback by design; returning early would make the owner's referenced state destructible while the callback is still using it.

try_acquire()

Lease pulp::runtime::AliveToken::try_acquire ( const Handle & handle )

inlinestaticnoexcept

Atomically admit one callback before teardown can retire the owner.

Checking is_alive() and then using a captured owner reference is not a lifetime proof: retire() can run between those two operations. Callers that will dereference owner-backed state must hold the returned Lease for the complete callback. A retired or empty handle returns an empty lease and the callback must fail closed. Acquiring a lease takes a mutex, so this API is for editor/host control callbacks; realtime audio paths should keep using the lock-free is_alive() check and must not dereference state whose owner can be destroyed concurrently.

---

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

• /home/runner/work/pulp/pulp/core/runtime/include/pulp/runtime/alive_token.hpp