EntropyEngine::Networking::ConnectionManager

EntropyEngine::Networking::ConnectionManager

Slot-based connection manager with platform-agnostic API. More…

#include <ConnectionManager.h>

Inherits from EntropyEngine::Core::EntropyObject

Public Classes

	Name
struct	ManagerMetrics Lightweight aggregate metrics snapshot for observability.

Public Functions

	Name
	~ConnectionManager()
Result< void >	trySend(const ConnectionHandle & handle, 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(const ConnectionHandle & handle, std::function< void(ConnectionState)> callback) Sets state callback (called by handle.setStateCallback()).
void	setMessageCallback(const ConnectionHandle & handle, std::function< void(const std::vector< uint8_t > &)> callback) Sets message callback (called by handle.setMessageCallback()).
Result< void >	sendUnreliable(const ConnectionHandle & handle, const std::vector< uint8_t > & data) Sends data over unreliable channel (called by handle.sendUnreliable()).
Result< void >	send(const ConnectionHandle & handle, const std::vector< uint8_t > & data) Sends data over reliable channel (called by handle.send()).
ConnectionManager &	operator=(const ConnectionManager & ) =delete
ConnectionHandle	openRemoteConnection(const std::string & signalingUrl) Opens a remote connection using WebRTC with internal signaling.
ConnectionHandle	openRemoteConnection(const std::string & signalingServer, WebRTCConfig config, SignalingCallbacks callbacks) Opens a remote connection using WebRTC with explicit callbacks.
ConnectionHandle	openLocalConnection(const std::string & endpoint) Opens a local connection with platform-appropriate backend.
ConnectionHandle	openConnection(ConnectionConfig config) Opens connection with explicit configuration.
bool	isValidHandle(const ConnectionHandle & handle) const Validates handle (called by handle.valid()).
bool	isConnected(const ConnectionHandle & handle) const Checks if connected (called by handle.isConnected()).
ConnectionStats	getStats(const ConnectionHandle & handle) const Gets connection statistics (called by handle.getStats()).
ConnectionState	getState(const ConnectionHandle & handle) const Gets connection state (called by handle.getState()).
ManagerMetrics	getManagerMetrics() const Get a snapshot of aggregate metrics across all connections.
ConnectionType	getConnectionType(const ConnectionHandle & handle) const Gets connection type (called by handle.getType()).
NetworkConnection *	getConnectionPointer(const ConnectionHandle & handle)
Result< void >	disconnect(const ConnectionHandle & handle) Disconnects connection (called by handle.disconnect()).
Result< void >	connect(const ConnectionHandle & handle) Initiates connection (called by handle.connect()).
Result< void >	closeConnection(const ConnectionHandle & handle) Closes connection and frees slot (called by handle.close()).
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.
size_t	capacity() const Gets maximum capacity.
ConnectionHandle	adoptConnection(std::unique_ptr< NetworkConnection > backend, ConnectionType type) Adopts a pre-constructed NetworkConnection backend.
size_t	activeCount() const Gets active connection count.
	ConnectionManager(size_t capacity) Constructs connection manager with specified capacity.
	ConnectionManager(const ConnectionManager & ) =delete

Friends

	Name
class	SessionManager
class	ConnectionHandle

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::ConnectionManager;

Slot-based connection manager with platform-agnostic API.

ConnectionManager follows the WorkContractGroup pattern - it owns connection slots and returns generation-stamped handles. Provides platform abstraction for write-once-deploy-everywhere:

• Local connections: Auto-selects Unix socket (Linux/macOS) or Named pipe (Windows)
• Remote connections: Uses WebRTC on all platforms

Handle lifecycle:

1. Create connection via openLocalConnection() or openRemoteConnection()
2. Returns ConnectionHandle stamped with (manager + index + generation)
3. Use handle for all operations (connect, send, etc.)
4. Handle becomes invalid after disconnect or release

Thread Safety: All public methods are thread-safe. Internal operations use lock-free algorithms or minimal per-slot locking. Callbacks are invoked using lock-free atomic shared_ptr access to prevent deadlocks.

ConnectionManager connMgr(1024);  // capacity: 1024 connections

// Platform-agnostic local connection
auto local = connMgr.openLocalConnection("/tmp/entropy.sock");
local.connect().wait();

// Cross-platform remote connection
auto remote = connMgr.openRemoteConnection(server, webrtcConfig, callbacks);
remote.connect().wait();

Public Functions Documentation

function ~ConnectionManager

~ConnectionManager()

function trySend

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

Non-blocking send that returns WouldBlock on backpressure.

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(
    const ConnectionHandle & handle,
    std::function< void(ConnectionState)> callback
)

Sets state callback (called by handle.setStateCallback()).

Parameters:

• handle Connection handle
• callback Function called when connection state changes

function setMessageCallback

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

Sets message callback (called by handle.setMessageCallback()).

Parameters:

• handle Connection handle
• callback Function called when messages are received

function sendUnreliable

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

Sends data over unreliable channel (called by handle.sendUnreliable()).

Parameters:

• handle Connection handle
• data Bytes to send

Return: Result indicating success or failure

function send

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

Sends data over reliable channel (called by handle.send()).

Parameters:

• handle Connection handle
• data Bytes to send

Return: Result indicating success or failure

function operator=

ConnectionManager & operator=(
    const ConnectionManager &
) =delete

function openRemoteConnection

ConnectionHandle openRemoteConnection(
    const std::string & signalingUrl
)

Opens a remote connection using WebRTC with internal signaling.

Parameters:

• signalingUrl WebSocket URL for signaling (e.g., “ws://localhost:8080”)

Return: ConnectionHandle for operations, or invalid if full

Simplified client-side API - WebSocket signaling handled internally.

function openRemoteConnection

ConnectionHandle openRemoteConnection(
    const std::string & signalingServer,
    WebRTCConfig config,
    SignalingCallbacks callbacks
)

Opens a remote connection using WebRTC with explicit callbacks.

Parameters:

• signalingServer WebSocket URL for signaling
• config WebRTC configuration (ICE servers, etc.)
• callbacks Signaling callbacks for SDP/ICE exchange

Return: ConnectionHandle for operations, or invalid if full

Advanced API for server-side or custom signaling.

function openLocalConnection

ConnectionHandle openLocalConnection(
    const std::string & endpoint
)

Opens a local connection with platform-appropriate backend.

Parameters:

• endpoint Path to socket/pipe

Return: ConnectionHandle for operations, or invalid if full

Platform auto-selection:

• Linux/macOS: Unix domain socket
• Windows: Named pipe
• macOS (future): Can use XPC with config

function openConnection

ConnectionHandle openConnection(
    ConnectionConfig config
)

Opens connection with explicit configuration.

Parameters:

• config Connection configuration

Return: ConnectionHandle for operations, or invalid if full

Advanced API for full control over backend selection.

function isValidHandle

bool isValidHandle(
    const ConnectionHandle & handle
) const

Validates handle (called by handle.valid()).

Parameters:

• handle Connection handle

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

function isConnected

bool isConnected(
    const ConnectionHandle & handle
) const

Checks if connected (called by handle.isConnected()).

Parameters:

• handle Connection handle

Return: true if connection is established

function getStats

ConnectionStats getStats(
    const ConnectionHandle & handle
) const

Gets connection statistics (called by handle.getStats()).

Parameters:

• handle Connection handle

Return: Statistics structure

function getState

ConnectionState getState(
    const ConnectionHandle & handle
) const

Gets connection state (called by handle.getState()).

Parameters:

• handle Connection handle

Return: Current connection state

function getManagerMetrics

ManagerMetrics getManagerMetrics() const

Get a snapshot of aggregate metrics across all connections.

function getConnectionType

ConnectionType getConnectionType(
    const ConnectionHandle & handle
) const

Gets connection type (called by handle.getType()).

Parameters:

• handle Connection handle

Return: ConnectionType (Local or Remote)

function getConnectionPointer

NetworkConnection * getConnectionPointer(
    const ConnectionHandle & handle
)

function disconnect

Result< void > disconnect(
    const ConnectionHandle & handle
)

Disconnects connection (called by handle.disconnect()).

Parameters:

• handle Connection handle

Return: Result indicating success or failure

function connect

Result< void > connect(
    const ConnectionHandle & handle
)

Initiates connection (called by handle.connect()).

Parameters:

• handle Connection handle

Return: Result indicating success or failure

function closeConnection

Result< void > closeConnection(
    const ConnectionHandle & handle
)

Closes connection and frees slot (called by handle.close()).

Parameters:

• handle Connection handle

Return: Result indicating success or failure

Disconnects the connection (if connected) and returns the slot to the free list. After calling this, the handle becomes invalid and the slot can 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 capacity

inline size_t capacity() const

Gets maximum capacity.

Return: Maximum number of connections this manager can handle

function adoptConnection

ConnectionHandle adoptConnection(
    std::unique_ptr< NetworkConnection > backend,
    ConnectionType type
)

Adopts a pre-constructed NetworkConnection backend.

Parameters:

• backend Already-constructed connection (e.g., from accept())
• type Connection type (Local or Remote)

Return: ConnectionHandle for operations, or invalid if full

Used by LocalServer to wrap accepted connections. Allocates a slot, installs the backend, and wires up state synchronization.

function activeCount

inline size_t activeCount() const

Gets active connection count.

Return: Number of currently allocated connections

function ConnectionManager

explicit ConnectionManager(
    size_t capacity
)

Constructs connection manager with specified capacity.

Parameters:

• capacity Maximum number of connections (typically 1024-4096)

Pre-allocates all slots for lock-free operation. Choose capacity based on maximum concurrent connections.

function ConnectionManager

ConnectionManager(
    const ConnectionManager &
) =delete

Friends

friend SessionManager

friend class SessionManager(
    SessionManager
);

friend ConnectionHandle

friend class ConnectionHandle(
    ConnectionHandle
);

---

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