EntropyEngine::Core::EntropyObject

Ref-counted base with optional handle stamping and basic introspection. More…

#include <EntropyObject.h>

Protected Classes

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

Public Functions

	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.
virtual std::string	toString() const Human-readable short string (class@ptr by default).
void	retain() const Increments the reference count.
void	release() const Decrements the reference count and deletes when it reaches zero.
uint32_t	refCount() const Current reference count (approximate under contention).
EntropyObject &	operator=(const EntropyObject & ) =delete
EntropyObject &	operator=(EntropyObject && ) =delete
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.
virtual const char *	className() const Runtime class name for diagnostics and reflection.
virtual uint64_t	classHash() const Stable type hash for cross-language identification.
	EntropyObject() =default
	EntropyObject(EntropyObject && ) =delete
	EntropyObject(const EntropyObject & ) =delete

Protected Functions

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

Protected Attributes

	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

	Name
struct	HandleAccess

Detailed Description

class EntropyEngine::Core::EntropyObject;

Ref-counted base with optional handle stamping and basic introspection.

Designed for safe sharing across module/language boundaries. Reference count operations are thread-safe. When stamped with a handle identity, the object can participate in owner/index/generation validation without coupling to a specific handle type.

Public Functions Documentation

function ~EntropyObject

virtual ~EntropyObject() =default

function typeInfo

inline virtual const TypeSystem::TypeInfo * typeInfo() const

Optional richer type information; may be null.

function tryRetain

bool tryRetain() const

Attempts to retain only if the object is still alive.

Return: true on success (reference acquired), false if object already dead

Use when you need to safely grab a reference from a background thread without racing destruction. If the refcount has already reached zero, tryRetain() returns false and the object must not be used.

// Example: Try to use an object that might be concurrently released
if (obj->tryRetain()) {
    doWork(obj);
    obj->release();
} // else: object was already destroyed or being destroyed

function toString

virtual std::string toString() const

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

Reimplemented by: EntropyEngine::Core::Concurrency::WorkContractGroup::toString, EntropyEngine::Core::Concurrency::WorkContractHandle::toString, EntropyEngine::Networking::ConnectionHandle::toString, EntropyEngine::Networking::ConnectionManager::toString, EntropyEngine::Networking::NamedPipeServer::toString, EntropyEngine::Networking::SessionHandle::toString, EntropyEngine::Networking::SessionManager::toString, EntropyEngine::Networking::UnixSocketServer::toString

function retain

void retain() const

Increments the reference count.

Note: Thread-safe; may be called from any thread.

function release

void release() const

Decrements the reference count and deletes when it reaches zero.

Note: Thread-safe; may delete the object on the calling thread when count hits zero.

function refCount

uint32_t refCount() const

Current reference count (approximate under contention).

function operator=

EntropyObject & operator=(
    const EntropyObject &
) =delete

function operator=

EntropyObject & operator=(
    EntropyObject &&
) =delete

function hasHandle

inline bool hasHandle() const

Return: true if an owner has stamped this object with handle identity

function handleOwnerAs

template <class OwnerT >
inline OwnerT * handleOwnerAs() const

Returns the stamped owner pointer cast to the requested type.

Template Parameters:

OwnerT Expected owner class type (e.g., WorkContractGroup)

Return: Owner pointer cast to OwnerT*, or nullptr if not stamped

Note: Safe by construction: owners stamp the object with the true owner pointer

function handleOwner

inline const void * handleOwner() const

Return: Owner pointer that stamped this object, or null if none

function handleIndex

inline uint32_t handleIndex() const

Return: Index value stamped by the owner (undefined if !hasHandle())

function handleId

inline uint64_t handleId() const

Return: 64-bit packed index:generation identifier (undefined if !hasHandle())

function handleGeneration

inline uint32_t handleGeneration() const

Return: Generation value stamped by the owner (undefined if !hasHandle())

function getWeakControlBlock

WeakControlBlock * getWeakControlBlock() const

Lazily retrieves or creates the weak control block.

Return: Pointer to the control block (retained by the object)

function description

virtual std::string description() const

Long-form description; defaults to toString().

Reimplemented by: EntropyEngine::Core::Concurrency::WorkContractGroup::description

function debugString

virtual std::string debugString() const

Debug-oriented string including refcount and handle when present.

Reimplemented by: EntropyEngine::Core::Concurrency::WorkContractGroup::debugString

function className

inline virtual const char * className() const

Runtime class name for diagnostics and reflection.

function classHash

virtual uint64_t classHash() const

Stable type hash for cross-language identification.

Reimplemented by: EntropyEngine::Core::Concurrency::WorkContractGroup::classHash, EntropyEngine::Core::Concurrency::WorkContractHandle::classHash, EntropyEngine::Core::Graph::AcyclicNodeHandle::classHash, EntropyEngine::Core::Graph::AcyclicNodeHandle::classHash, EntropyEngine::Networking::ConnectionHandle::classHash, EntropyEngine::Networking::ConnectionManager::classHash, EntropyEngine::Networking::NamedPipeServer::classHash, EntropyEngine::Networking::SessionHandle::classHash, EntropyEngine::Networking::SessionManager::classHash, EntropyEngine::Networking::UnixSocketServer::classHash

function EntropyObject

EntropyObject() =default

function EntropyObject

EntropyObject(
    EntropyObject &&
) =delete

function EntropyObject

EntropyObject(
    const EntropyObject &
) =delete

Protected Functions Documentation

function _setHandleIdentity

inline void _setHandleIdentity(
    void * owner,
    uint32_t index,
    uint32_t generation
)

function _clearHandleIdentity

inline void _clearHandleIdentity()

Protected Attributes Documentation

variable _weakBlock

std::atomic< WeakControlBlock * > _weakBlock {nullptr};

Lazily allocated control block for weak refs.

variable _refCount

std::atomic< uint32_t > _refCount {1};

Thread-safe retain/release counter.

variable _handle

struct EntropyEngine::Core::EntropyObject::HandleCore _handle;

Friends

friend HandleAccess

friend struct HandleAccess(
    HandleAccess
);

Updated on 2026-01-26 at 16:50:32 -0500