EntropyEngine::Core::Concurrency::WorkContractHandle

EntropyObject-stamped handle for work contracts. More…

#include <WorkContractHandle.h>

Inherits from EntropyEngine::Core::EntropyObject

Public Functions

	Name
bool	valid() const Checks whether this handle still refers to a live slot.
ScheduleResult	unschedule() Attempts to remove this contract from the ready set.
virtual std::string	toString() const override Human-readable short string (class@ptr by default).
ScheduleResult	schedule() Schedules this contract for execution.
void	release() Immediately frees this contract’s slot.
WorkContractHandle &	operator=(const WorkContractHandle & other)
WorkContractHandle &	operator=(WorkContractHandle && other)
bool	isScheduled() const Reports whether the contract is currently Scheduled.
bool	isExecuting() const Reports whether the contract is currently Executing.
virtual const char *	className() const override Runtime class name for diagnostics and reflection.
virtual uint64_t	classHash() const override Stable type hash for cross-language identification.
	WorkContractHandle() =default
	WorkContractHandle(const WorkContractHandle & other)
	WorkContractHandle(WorkContractHandle && other)

Friends

	Name
class	WorkContractGroup

Additional inherited members

Protected Classes inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleCore Optional handle identity stamped by an owner/registry.

Public Functions inherited from EntropyEngine::Core::EntropyObject

	Name
virtual	~EntropyObject() =default
virtual const TypeSystem::TypeInfo *	typeInfo() const Optional richer type information; may be null.
bool	tryRetain() const Attempts to retain only if the object is still alive.
void	retain() const Increments the reference count.
uint32_t	refCount() const Current reference count (approximate under contention).
bool	hasHandle() const
template <class OwnerT > OwnerT *	handleOwnerAs() const Returns the stamped owner pointer cast to the requested type.
const void *	handleOwner() const
uint32_t	handleIndex() const
uint64_t	handleId() const
uint32_t	handleGeneration() const
WeakControlBlock *	getWeakControlBlock() const Lazily retrieves or creates the weak control block.
virtual std::string	description() const Long-form description; defaults to toString().
virtual std::string	debugString() const Debug-oriented string including refcount and handle when present.
	EntropyObject() =default
	EntropyObject(EntropyObject && ) =delete
	EntropyObject(const EntropyObject & ) =delete

Protected Functions inherited from EntropyEngine::Core::EntropyObject

	Name
void	_setHandleIdentity(void * owner, uint32_t index, uint32_t generation)
void	_clearHandleIdentity()

Protected Attributes inherited from EntropyEngine::Core::EntropyObject

	Name
std::atomic< WeakControlBlock * >	_weakBlock Lazily allocated control block for weak refs.
std::atomic< uint32_t >	_refCount Thread-safe retain/release counter.
struct EntropyEngine::Core::EntropyObject::HandleCore	_handle

Friends inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleAccess

Detailed Description

class EntropyEngine::Core::Concurrency::WorkContractHandle;

EntropyObject-stamped handle for work contracts.

This handle derives from EntropyObject and carries a stamped identity: owner (WorkContractGroup*), slot index, and generation. The group is the source of truth; validation compares the stamp against the group’s slot.

Copy semantics:

Copying a handle copies only its stamped identity (no ownership transfer).
The group owns lifetime; when a slot is freed, the handle becomes invalid.

Typical workflow:

Create via WorkContractGroup::createContract()
Call schedule(), optionally unschedule()
After execution starts or release(), valid() becomes false

WorkContractGroup group(1024);
auto h = group.createContract([]{ doWork(); });
if (h.schedule() == ScheduleResult::Scheduled) { // queued }
if (h.valid()) { // still schedulable }

Public Functions Documentation

function valid

bool valid() const

Checks whether this handle still refers to a live slot.

Return: true if owner, index, and generation match a live slot

function unschedule

ScheduleResult unschedule()

Attempts to remove this contract from the ready set.

Return: NotScheduled on success, Executing if too late, or Invalid

Succeeds only when in Scheduled state; cannot cancel while Executing.

function toString

virtual std::string toString() const override

Human-readable short string (class@ptr by default).

Reimplements: EntropyEngine::Core::EntropyObject::toString

function schedule

ScheduleResult schedule()

Schedules this contract for execution.

Return: Scheduled, AlreadyScheduled, Executing, or Invalid

Transitions Allocated -> Scheduled. No-op if already scheduled.

auto h = group.createContract([]{});
if (h.schedule() == ScheduleResult::Scheduled) { // scheduled }

function release

void release()

Immediately frees this contract’s slot.

Clears scheduling state and returns the slot to the free list. After this, valid() is false.

function operator=

inline WorkContractHandle & operator=(
    const WorkContractHandle & other
)

function operator=

inline WorkContractHandle & operator=(
    WorkContractHandle && other
)

function isScheduled

bool isScheduled() const

Reports whether the contract is currently Scheduled.

Return: true if scheduled and waiting for execution

function isExecuting

bool isExecuting() const

Reports whether the contract is currently Executing.

Return: true if actively running

function className

inline virtual const char * className() const override

Runtime class name for diagnostics and reflection.

Reimplements: EntropyEngine::Core::EntropyObject::className

function classHash

virtual uint64_t classHash() const override

Stable type hash for cross-language identification.

Reimplements: EntropyEngine::Core::EntropyObject::classHash

function WorkContractHandle

WorkContractHandle() =default

function WorkContractHandle

inline WorkContractHandle(
    const WorkContractHandle & other
)

function WorkContractHandle

inline WorkContractHandle(
    WorkContractHandle && other
)

Friends

friend WorkContractGroup

friend class WorkContractGroup(
    WorkContractGroup
);

Updated on 2026-01-26 at 17:14:35 -0500