EntropyEngine::Networking::NetworkConnection

Abstract base interface for network connections. More…

#include <NetworkConnection.h>

Inherits from EntropyEngine::Core::EntropyObject

Inherited by EntropyEngine::Networking::NamedPipeConnection, EntropyEngine::Networking::SharedMemoryConnection, EntropyEngine::Networking::UnixSocketConnection, EntropyEngine::Networking::WebRTCConnection

Public Types

	Name
using std::function< void(ConnectionState)>	StateCallback Callback for state changes.
using std::function< void(const std::vector< uint8_t > &)>	MessageCallback Callback for received messages.
using std::function< void(const std::string &channel, const std::vector< uint8_t > &)>	ChannelMessageCallback

Public Functions

	Name
virtual	~NetworkConnection() =default
virtual Result< void >	trySend(const std::vector< uint8_t > & data) Non-blocking send with backpressure detection.
virtual bool	supportsMultipleChannels() const Checks if this backend supports multiple channels.
virtual void	startReceiving() Starts the receive thread for adopted connections.
void	setStateCallback(StateCallback callback) Sets callback for state changes.
void	setMessageCallback(MessageCallback callback) Sets callback for incoming messages.
virtual void	setChannelMessageCallback(const std::string & channel, MessageCallback callback) Sets callback for messages received on a specific channel.
virtual Result< void >	sendUnreliable(const std::vector< uint8_t > & data) =0 Sends data over the unreliable channel (if available).
virtual Result< void >	sendOnChannel(const std::string & channel, const std::vector< uint8_t > & data) Sends data on a named channel.
virtual Result< void >	send(const std::vector< uint8_t > & data) =0 Sends data over the reliable channel.
virtual Result< void >	openChannel(const std::string & channel) Opens a named channel (creates if needed).
bool	isShuttingDown() const Check if callbacks are being shut down (safe for use in static callbacks).
virtual bool	isConnected() const =0 Checks if connection is established.
virtual bool	isChannelOpen(const std::string & channel) const Checks if a named channel is open and ready for data.
virtual ConnectionType	getType() const =0 Gets connection type (Local or Remote).
virtual ConnectionStats	getStats() const =0 Gets connection statistics.
virtual ConnectionState	getState() const =0 Gets current connection state.
virtual Result< void >	disconnect() =0 Disconnects from endpoint.
virtual Result< void >	connect() =0 Initiates connection to endpoint.

Protected Functions

	Name
void	shutdownCallbacks() Shuts down callbacks and waits for in-flight invocations.
void	onStateChanged(ConnectionState state) Invokes state callback with lifetime guards.
void	onMessageReceived(const std::vector< uint8_t > & data) Invokes message callback with lifetime guards.
void	onChannelMessageReceived(const std::string & channel, const std::vector< uint8_t > & data) Invokes channel-specific message callback with lifetime guards.
	NetworkConnection() =default

Public Attributes

	Name
const char *	CHANNEL_CONTROL Well-known channel names.
const char *	CHANNEL_ASSET_UPLOAD Bulk asset uploads.
const char *	CHANNEL_ASSET_DOWNLOAD Bulk asset downloads.

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.
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 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::NetworkConnection;

Abstract base interface for network connections.

NetworkConnection defines the interface that all connection backends must implement. Derives from EntropyObject for type system integration. Connections are created by ConnectionManager and accessed via ConnectionHandle.

Implementations:

UnixSocketConnection (Linux/macOS local IPC)
NamedPipeConnection (Windows local IPC)
WebRTCConnection (all platforms, remote)
XPCConnection (macOS, local IPC)

Thread Safety: All methods are thread-safe unless documented otherwise. Callbacks are invoked with reference-counted guards to prevent use-after-free.

Public Types Documentation

using StateCallback

using EntropyEngine::Networking::NetworkConnection::StateCallback = std::function<void(ConnectionState)>;

Callback for state changes.

using MessageCallback

using EntropyEngine::Networking::NetworkConnection::MessageCallback = std::function<void(const std::vector<uint8_t>&)>;

Callback for received messages.

using ChannelMessageCallback

using EntropyEngine::Networking::NetworkConnection::ChannelMessageCallback = std::function<void(const std::string& channel, const std::vector<uint8_t>&)>;

Public Functions Documentation

function ~NetworkConnection

virtual ~NetworkConnection() =default

function trySend

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

Non-blocking send with backpressure detection.

Parameters:

data Bytes to send

Return: Result with WouldBlock error if backpressured, or InvalidParameter if not supported

Reimplemented by: EntropyEngine::Networking::NamedPipeConnection::trySend, EntropyEngine::Networking::SharedMemoryConnection::trySend, EntropyEngine::Networking::UnixSocketConnection::trySend, EntropyEngine::Networking::WebRTCConnection::trySend

function supportsMultipleChannels

inline virtual bool supportsMultipleChannels() const

Checks if this backend supports multiple channels.

Return: true if sendOnChannel uses separate channels

Reimplemented by: EntropyEngine::Networking::WebRTCConnection::supportsMultipleChannels

function startReceiving

inline virtual void startReceiving()

Starts the receive thread for adopted connections.

Reimplemented by: EntropyEngine::Networking::NamedPipeConnection::startReceiving, EntropyEngine::Networking::SharedMemoryConnection::startReceiving, EntropyEngine::Networking::UnixSocketConnection::startReceiving

For connections created via accept(), the receive thread must NOT start in the constructor. Instead, ConnectionManager calls this after setting up callbacks to avoid race conditions where messages arrive before handlers are registered.

For client-side connections (via connect()), receive thread starts automatically in connect() - this method is a no-op.

function setStateCallback

inline void setStateCallback(
    StateCallback callback
)

Sets callback for state changes.

Parameters:

callback Function called when connection state changes

Thread-safe: Can be called from any thread.

function setMessageCallback

inline void setMessageCallback(
    MessageCallback callback
)

Sets callback for incoming messages.

Parameters:

callback Function called when messages arrive

Thread-safe: Can be called from any thread.

function setChannelMessageCallback

inline virtual void setChannelMessageCallback(
    const std::string & channel,
    MessageCallback callback
)

Sets callback for messages received on a specific channel.

Parameters:

channel Channel name
callback Function called when messages arrive on this channel

function sendUnreliable

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

Sends data over the unreliable channel (if available).

Parameters:

data Bytes to send

Return: Result indicating success or failure reason

Reimplemented by: EntropyEngine::Networking::NamedPipeConnection::sendUnreliable, EntropyEngine::Networking::SharedMemoryConnection::sendUnreliable, EntropyEngine::Networking::UnixSocketConnection::sendUnreliable, EntropyEngine::Networking::WebRTCConnection::sendUnreliable

Falls back to reliable channel if unreliable is not supported. Thread-Safety: Same mutex contention considerations as send().

function sendOnChannel

inline virtual Result< void > sendOnChannel(
    const std::string & channel,
    const std::vector< uint8_t > & data
)

Sends data on a named channel.

Parameters:

channel Channel name (use CHANNEL_* constants)
data Bytes to send

Return: Result indicating success or failure

Reimplemented by: EntropyEngine::Networking::WebRTCConnection::sendOnChannel

For backends that support multiple channels (WebRTC), this sends on the specified channel. For single-channel backends (Unix socket, named pipe), this falls back to the default channel.

function send

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

Sends data over the reliable channel.

Parameters:

data Bytes to send

Return: Result indicating success or failure reason

Reimplemented by: EntropyEngine::Networking::NamedPipeConnection::send, EntropyEngine::Networking::SharedMemoryConnection::send, EntropyEngine::Networking::UnixSocketConnection::send, EntropyEngine::Networking::WebRTCConnection::send

Thread-Safety: All send operations are serialized through a per-connection mutex. For high-throughput scenarios with large messages, this can become a bottleneck. Consider:

Using sendUnreliable for non-critical data
Batching multiple small messages into larger payloads
Using multiple connections for parallel sends

function openChannel

inline virtual Result< void > openChannel(
    const std::string & channel
)

Opens a named channel (creates if needed).

Parameters:

channel Channel name

Return: Result indicating success or failure

Reimplemented by: EntropyEngine::Networking::WebRTCConnection::openChannel

For WebRTC, this creates a new data channel. For other backends, this is a no-op since they use a single channel.

function isShuttingDown

inline bool isShuttingDown() const

Check if callbacks are being shut down (safe for use in static callbacks).

Return: true if shutdownCallbacks() has been called

function isConnected

virtual bool isConnected() const =0

Checks if connection is established.

Return: true if state is Connected

Reimplemented by: EntropyEngine::Networking::NamedPipeConnection::isConnected, EntropyEngine::Networking::SharedMemoryConnection::isConnected, EntropyEngine::Networking::UnixSocketConnection::isConnected, EntropyEngine::Networking::WebRTCConnection::isConnected

function isChannelOpen

inline virtual bool isChannelOpen(
    const std::string & channel
) const

Checks if a named channel is open and ready for data.

Parameters:

channel Channel name

Return: true if channel is open (or backend doesn’t support channels)

Reimplemented by: EntropyEngine::Networking::WebRTCConnection::isChannelOpen

function getType

virtual ConnectionType getType() const =0

Gets connection type (Local or Remote).

Return: Connection type determined at creation

Reimplemented by: EntropyEngine::Networking::NamedPipeConnection::getType, EntropyEngine::Networking::SharedMemoryConnection::getType, EntropyEngine::Networking::UnixSocketConnection::getType, EntropyEngine::Networking::WebRTCConnection::getType

function getStats

virtual ConnectionStats getStats() const =0

Gets connection statistics.

Return: Stats with bytes/messages sent/received

Reimplemented by: EntropyEngine::Networking::NamedPipeConnection::getStats, EntropyEngine::Networking::SharedMemoryConnection::getStats, EntropyEngine::Networking::UnixSocketConnection::getStats, EntropyEngine::Networking::WebRTCConnection::getStats

function getState

virtual ConnectionState getState() const =0

Gets current connection state.

Return: Connection state (Disconnected, Connecting, Connected, etc.)

Reimplemented by: EntropyEngine::Networking::NamedPipeConnection::getState, EntropyEngine::Networking::SharedMemoryConnection::getState, EntropyEngine::Networking::UnixSocketConnection::getState, EntropyEngine::Networking::WebRTCConnection::getState

function disconnect

virtual Result< void > disconnect() =0

Disconnects from endpoint.

Return: Result indicating success or failure

Reimplemented by: EntropyEngine::Networking::NamedPipeConnection::disconnect, EntropyEngine::Networking::SharedMemoryConnection::disconnect, EntropyEngine::Networking::UnixSocketConnection::disconnect, EntropyEngine::Networking::WebRTCConnection::disconnect

function connect

virtual Result< void > connect() =0

Initiates connection to endpoint.

Return: Result indicating success or failure

Reimplemented by: EntropyEngine::Networking::NamedPipeConnection::connect, EntropyEngine::Networking::SharedMemoryConnection::connect, EntropyEngine::Networking::UnixSocketConnection::connect, EntropyEngine::Networking::WebRTCConnection::connect

Protected Functions Documentation

function shutdownCallbacks

inline void shutdownCallbacks()

Shuts down callbacks and waits for in-flight invocations.

Sets shutdown flag and spin-waits for active callbacks to complete. Call this from derived class destructor BEFORE base destructor runs.

function onStateChanged

inline void onStateChanged(
    ConnectionState state
)

Invokes state callback with lifetime guards.

Parameters:

state New connection state

Called by derived classes when state changes. Uses RAII guard and shutdown flag to prevent use-after-free during destruction.

function onMessageReceived

inline void onMessageReceived(
    const std::vector< uint8_t > & data
)

Invokes message callback with lifetime guards.

Parameters:

data Received message bytes

Called by derived classes when messages arrive. Uses RAII guard and shutdown flag to prevent use-after-free during destruction.

function onChannelMessageReceived

inline void onChannelMessageReceived(
    const std::string & channel,
    const std::vector< uint8_t > & data
)

Invokes channel-specific message callback with lifetime guards.

Parameters:

channel Channel name the message arrived on
data Received message bytes

Called by derived classes when messages arrive on named channels.

function NetworkConnection

NetworkConnection() =default

Public Attributes Documentation

variable CHANNEL_CONTROL

static const char * CHANNEL_CONTROL = "control";

Well-known channel names.

Default control/protocol channel

variable CHANNEL_ASSET_UPLOAD

static const char * CHANNEL_ASSET_UPLOAD = "asset-upload";

Bulk asset uploads.

variable CHANNEL_ASSET_DOWNLOAD

static const char * CHANNEL_ASSET_DOWNLOAD = "asset-download";

Bulk asset downloads.

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