EntropyEngine::Networking::ConnectionHandle

EntropyEngine::Networking::ConnectionHandle

EntropyObject-stamped handle for network connections. More…

#include <ConnectionHandle.h>

Inherits from EntropyEngine::Core::EntropyObject

Public Functions

	Name
bool	valid() const Checks whether this handle still refers to a live connection.
Result< void >	trySend(const std::vector< uint8_t > & data) Non-blocking send that returns WouldBlock on backpressure.
virtual std::string	toString() const override Human-readable short string (class@ptr by default).
void	setStateCallback(std::function< void(ConnectionState)> callback) Sets callback for connection state changes.
void	setMessageCallback(std::function< void(const std::vector< uint8_t > &)> callback) Sets callback for incoming messages.
Result< void >	sendUnreliable(const std::vector< uint8_t > & data) Sends data over the unreliable channel (if available).
Result< void >	send(const std::vector< uint8_t > & data) Sends data over the reliable channel.
ConnectionHandle &	operator=(const ConnectionHandle & other)
ConnectionHandle &	operator=(ConnectionHandle && other)
bool	isConnected() const Checks if connection is established and ready.
ConnectionType	getType() const Gets the connection type (Local or Remote).
ConnectionStats	getStats() const Gets connection statistics.
ConnectionState	getState() const Gets the current connection state.
Result< void >	disconnect() Disconnects from the endpoint.
Result< void >	connect() Initiates connection to the endpoint.
Result< void >	close() Closes connection and frees the slot.
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.
	ConnectionHandle() =default
	ConnectionHandle(const ConnectionHandle & other)
	ConnectionHandle(ConnectionHandle && other)

Friends

	Name
class	ConnectionManager

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.
void	release() const Decrements the reference count and deletes when it reaches zero.
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::Networking::ConnectionHandle;

EntropyObject-stamped handle for network connections.

ConnectionHandle follows the WorkContractHandle pattern - it’s an EntropyObject stamped with (owner + index + generation) that delegates operations to ConnectionManager.

The handle is the primary API for connection operations:

• connect() / disconnect()
• send() / sendUnreliable()
• State queries (isConnected, getState, getStats)
• Generation-based validation (valid())

Copy semantics:

• Copying a handle copies its stamped identity (not ownership transfer)
• The ConnectionManager owns lifetime; handles become invalid when freed

Typical workflow:

1. Create via ConnectionManager::openLocalConnection() or openRemoteConnection()
2. Call connect(), then send operations
3. After disconnect or release, valid() returns false

ConnectionManager connMgr(1024);
auto h = connMgr.openLocalConnection("/tmp/entropy.sock");
h.connect().wait();
if (h.isConnected()) {
    h.send(data);
}

Public Functions Documentation

function valid

bool valid() const

Checks whether this handle still refers to a live connection.

Return: true if handle is valid and refers to an allocated connection

Validates that the handle’s owner, index, and generation match the ConnectionManager’s current slot state.

function trySend

Result< void > trySend(
    const std::vector< uint8_t > & data
)

Non-blocking send that returns WouldBlock on backpressure.

Parameters:

• data Bytes to send

function toString

virtual std::string toString() const override

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

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

function setStateCallback

void setStateCallback(
    std::function< void(ConnectionState)> callback
)

Sets callback for connection state changes.

Parameters:

• callback Function called when connection state changes

Convenience method that delegates to ConnectionManager. Avoids exposing NetworkConnection backend directly.

function setMessageCallback

void setMessageCallback(
    std::function< void(const std::vector< uint8_t > &)> callback
)

Sets callback for incoming messages.

Parameters:

• callback Function called when messages are received

Convenience method that delegates to ConnectionManager. Avoids exposing NetworkConnection backend directly.

function sendUnreliable

Result< void > sendUnreliable(
    const std::vector< uint8_t > & data
)

Sends data over the unreliable channel (if available).

Parameters:

• data Bytes to send

Return: Result indicating success or failure reason

Best-effort delivery with no ordering guarantees. Falls back to reliable channel if unreliable is not supported by the backend.

function send

Result< void > send(
    const std::vector< uint8_t > & data
)

Sends data over the reliable channel.

Parameters:

• data Bytes to send

Return: Result indicating success or failure reason

Data is guaranteed to arrive in order and without loss.

function operator=

inline ConnectionHandle & operator=(
    const ConnectionHandle & other
)

function operator=

inline ConnectionHandle & operator=(
    ConnectionHandle && other
)

function isConnected

bool isConnected() const

Checks if connection is established and ready.

Return: true if state is Connected

function getType

ConnectionType getType() const

Gets the connection type (Local or Remote).

Return: Connection type determined at creation

function getStats

ConnectionStats getStats() const

Gets connection statistics.

Return: Stats structure with byte/message counts

function getState

ConnectionState getState() const

Gets the current connection state.

Return: Current connection state, or Disconnected if handle is invalid

function disconnect

Result< void > disconnect()

Disconnects from the endpoint.

Return: Result indicating success or failure reason

Gracefully closes the connection and transitions to Disconnected state. Does NOT free the slot - use close() for that.

function connect

Result< void > connect()

Initiates connection to the endpoint.

Return: Result indicating success or failure reason

Transitions from Disconnected to Connecting state, then to Connected when ready.

function close

Result< void > close()

Closes connection and frees the slot.

Return: Result indicating success or failure reason

Disconnects (if connected) and returns the slot to the free list. After calling close(), valid() will return false and the handle cannot be reused.

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 ConnectionHandle

ConnectionHandle() =default

function ConnectionHandle

inline ConnectionHandle(
    const ConnectionHandle & other
)

function ConnectionHandle

inline ConnectionHandle(
    ConnectionHandle && other
)

Friends

friend ConnectionManager

friend class ConnectionManager(
    ConnectionManager
);

---

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