EntropyEngine::Networking::UnixSocketConnection

Unix domain socket implementation for local IPC. More…

#include <UnixSocketConnection.h>

Inherits from EntropyEngine::Networking::NetworkConnection, EntropyEngine::Core::EntropyObject

Public Functions

	Name
	~UnixSocketConnection() override Destructor ensures clean shutdown.
virtual Result< void >	trySend(const std::vector< uint8_t > & data) override Non-blocking send with backpressure detection.
virtual void	startReceiving() override Starts the receive thread for adopted connections.
virtual Result< void >	sendUnreliable(const std::vector< uint8_t > & data) override Sends data over the unreliable channel (if available).
virtual Result< void >	send(const std::vector< uint8_t > & data) override Sends data over the reliable channel.
virtual bool	isConnected() const override Checks if connection is established.
virtual ConnectionType	getType() const override Gets connection type (Local or Remote).
virtual ConnectionStats	getStats() const override Gets connection statistics.
virtual ConnectionState	getState() const override Gets current connection state.
virtual Result< void >	disconnect() override Disconnects from endpoint.
virtual Result< void >	connect() override Initiates connection to endpoint.
	UnixSocketConnection(std::string socketPath) Constructs client-side connection to socket path.
	UnixSocketConnection(std::string socketPath, const struct ConnectionConfig * cfg) Constructs client-side connection with configuration.
	UnixSocketConnection(int connectedSocketFd, std::string peerInfo) Constructs server-side connection from accepted socket.

Additional inherited members

Public Types inherited from EntropyEngine::Networking::NetworkConnection

	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 inherited from EntropyEngine::Networking::NetworkConnection

	Name
virtual	~NetworkConnection() =default
virtual bool	supportsMultipleChannels() const Checks if this backend supports multiple channels.
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 >	sendOnChannel(const std::string & channel, const std::vector< uint8_t > & data) Sends data on a named 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	isChannelOpen(const std::string & channel) const Checks if a named channel is open and ready for data.

Protected Functions inherited from EntropyEngine::Networking::NetworkConnection

	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 inherited from EntropyEngine::Networking::NetworkConnection

	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.

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

Unix domain socket implementation for local IPC.

UnixSocketConnection provides reliable, ordered message delivery using Unix domain sockets (AF_UNIX). Offers significantly lower latency and higher throughput than TCP loopback for local communication.

Features:

Length-prefixed framing (uint32_t length + payload)
Dedicated receive thread for async message delivery
Configurable socket buffer sizes (SO_SNDBUF/SO_RCVBUF)
Configurable send/receive timeouts with poll-based retries
Atomic statistics tracking
Non-blocking send support via trySend()

Platform support: Linux, macOS (Unix systems only)

Thread Safety: All public methods are thread-safe. Send operations are serialized via mutex. Receive thread runs independently and invokes callbacks.

// Client-side usage
ConnectionConfig cfg;
cfg.endpoint = "/tmp/entropy.sock";
cfg.connectTimeoutMs = 5000;
cfg.socketSendBuf = 256 * 1024;  // 256 KB send buffer
cfg.socketRecvBuf = 256 * 1024;  // 256 KB receive buffer

auto conn = std::make_unique<UnixSocketConnection>(cfg.endpoint, &cfg);
conn->setMessageCallback([](const std::vector<uint8_t>& data) {
    std::cout << "Received " << data.size() << " bytes\n";
});

auto result = conn->connect();
if (result.success()) {
    std::vector<uint8_t> msg = {'h', 'e', 'l', 'l', 'o'};
    conn->send(msg);
}

// Server-side usage (after accept())
int clientFd = accept(serverFd, nullptr, nullptr);
auto clientConn = std::make_unique<UnixSocketConnection>(clientFd, "client-1");
clientConn->setMessageCallback([](const auto& data) { processMessage(data); });
// Connection is already established, ready to send/receive

Public Functions Documentation

function ~UnixSocketConnection

~UnixSocketConnection() override

Destructor ensures clean shutdown.

Stops receive thread, shuts down callbacks, closes socket.

function trySend

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

Non-blocking send with backpressure detection.

Parameters:

data Bytes to send

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

Reimplements: EntropyEngine::Networking::NetworkConnection::trySend

function startReceiving

virtual void startReceiving() override

Starts the receive thread for adopted connections.

Reimplements: EntropyEngine::Networking::NetworkConnection::startReceiving

Called by ConnectionManager::adoptConnection() AFTER callbacks are set. For connections created via connect(), receive thread starts in connect().

function sendUnreliable

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

Sends data over the unreliable channel (if available).

Parameters:

data Bytes to send

Return: Result indicating success or failure reason

Reimplements: EntropyEngine::Networking::NetworkConnection::sendUnreliable

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

function send

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

Sends data over the reliable channel.

Parameters:

data Bytes to send

Return: Result indicating success or failure reason

Reimplements: EntropyEngine::Networking::NetworkConnection::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 isConnected

inline virtual bool isConnected() const override

Checks if connection is established.

Return: true if state is Connected

Reimplements: EntropyEngine::Networking::NetworkConnection::isConnected

function getType

inline virtual ConnectionType getType() const override

Gets connection type (Local or Remote).

Return: Connection type determined at creation

Reimplements: EntropyEngine::Networking::NetworkConnection::getType

function getStats

virtual ConnectionStats getStats() const override

Gets connection statistics.

Return: Stats with bytes/messages sent/received

Reimplements: EntropyEngine::Networking::NetworkConnection::getStats

function getState

inline virtual ConnectionState getState() const override

Gets current connection state.

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

Reimplements: EntropyEngine::Networking::NetworkConnection::getState

function disconnect

virtual Result< void > disconnect() override

Disconnects from endpoint.

Return: Result indicating success or failure

Reimplements: EntropyEngine::Networking::NetworkConnection::disconnect

function connect

virtual Result< void > connect() override

Initiates connection to endpoint.

Return: Result indicating success or failure

Reimplements: EntropyEngine::Networking::NetworkConnection::connect

function UnixSocketConnection

UnixSocketConnection(
    std::string socketPath
)

Constructs client-side connection to socket path.

Parameters:

socketPath Path to Unix domain socket (e.g., “/tmp/entropy.sock”)

function UnixSocketConnection

UnixSocketConnection(
    std::string socketPath,
    const struct ConnectionConfig * cfg
)

Constructs client-side connection with configuration.

Parameters:

socketPath Path to Unix domain socket
cfg Connection configuration (timeouts, buffer sizes, etc.)

function UnixSocketConnection

UnixSocketConnection(
    int connectedSocketFd,
    std::string peerInfo
)

Constructs server-side connection from accepted socket.

Parameters:

connectedSocketFd File descriptor from accept()
peerInfo Identifier for logging/debugging

Used by LocalServer to wrap accepted client connections. Socket is already connected; no need to call connect().

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