EntropyEngine::Networking::SharedMemoryConnection

EntropyEngine::Networking::SharedMemoryConnection

Shared memory implementation for high-performance local IPC. More…

#include <SharedMemoryConnection.h>

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

Public Functions

	Name
	~SharedMemoryConnection() 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.
SharedMemoryConnection &	operator=(const SharedMemoryConnection & ) =delete
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.
size_t	getRegionSize() const Get the region size.
const std::string &	getRegionName() const Get the region name.
virtual Result< void >	disconnect() override Disconnects from endpoint.
virtual Result< void >	connect() override Initiates connection to endpoint.
	SharedMemoryConnection(std::string regionName) Constructs client-side connection to named region.
	SharedMemoryConnection(std::string regionName, const ConnectionConfig * cfg) Constructs client-side connection with configuration.
	SharedMemoryConnection(void * mappedRegion, size_t regionSize, std::string regionName, SharedMemory::NativeHandle handle, std::string peerInfo) Constructs server-side connection from already-mapped region.
	SharedMemoryConnection(const SharedMemoryConnection & ) =delete

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).
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.

Friends inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleAccess

Detailed Description

class EntropyEngine::Networking::SharedMemoryConnection;

Shared memory implementation for high-performance local IPC.

SharedMemoryConnection uses memory-mapped shared regions with lock-free ring buffers for ultra-low-latency message passing. Particularly suited for high-frequency property updates in game engines and graphics applications.

Features:

• Zero-copy message passing via ring buffers
• Lock-free synchronization using platform futex/ulock primitives
• Configurable region size (default 4 MiB)
• Length-prefixed message framing
• Backpressure detection via trySend()
• Atomic statistics tracking

Platform support: Linux (futex), macOS (ulock), Windows (WaitOnAddress)

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

Memory Layout:

+------------------+ offset 0
|   Control Block  |  (256 bytes: magic, version, atomics)
+------------------+
|  Server→Client   |  (half of data region)
|   Ring Buffer    |
+------------------+
|  Client→Server   |  (half of data region)
|   Ring Buffer    |
+------------------+

// Client-side usage
ConnectionConfig cfg;
cfg.endpoint = "entropy_canvas";
cfg.sharedMemoryRegionSize = 8 * 1024 * 1024;  // 8 MiB

auto conn = std::make_unique<SharedMemoryConnection>(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);
}

Public Functions Documentation

function ~SharedMemoryConnection

~SharedMemoryConnection() override

Destructor ensures clean shutdown.

Signals shutdown, stops receive thread, unmaps region, closes handle.

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 operator=

SharedMemoryConnection & operator=(
    const SharedMemoryConnection &
) =delete

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 getRegionSize

inline size_t getRegionSize() const

Get the region size.

Return: Size of the shared memory region in bytes

function getRegionName

inline const std::string & getRegionName() const

Get the region name.

Return: Region name used for this connection

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 SharedMemoryConnection

explicit SharedMemoryConnection(
    std::string regionName
)

Constructs client-side connection to named region.

Parameters:

• regionName Base name for shared memory regions

Client will connect to the discovery region and receive a per-connection region assignment from the server.

function SharedMemoryConnection

SharedMemoryConnection(
    std::string regionName,
    const ConnectionConfig * cfg
)

Constructs client-side connection with configuration.

Parameters:

• regionName Base name for shared memory regions
• cfg Connection configuration (region size, timeouts, etc.)

function SharedMemoryConnection

SharedMemoryConnection(
    void * mappedRegion,
    size_t regionSize,
    std::string regionName,
    SharedMemory::NativeHandle handle,
    std::string peerInfo
)

Constructs server-side connection from already-mapped region.

Parameters:

• mappedRegion Pointer to mapped shared memory region
• regionSize Size of the mapped region
• regionName Name of the region (for cleanup)
• handle Native handle to the region
• peerInfo Identifier for logging/debugging

Used by SharedMemoryServer to wrap accepted client connections. Region is already mapped; no need to call connect().

function SharedMemoryConnection

SharedMemoryConnection(
    const SharedMemoryConnection &
) =delete

---

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