EntropyEngine::Networking::SharedMemory

EntropyEngine::Networking::SharedMemory

Classes

	Name
struct	EntropyEngine::Networking::SharedMemory::SharedMemoryControlBlock Control block structure placed at the start of each shared memory region.
struct	EntropyEngine::Networking::SharedMemory::PlatformOps Platform-specific shared memory operations.
struct	EntropyEngine::Networking::SharedMemory::DiscoveryControlBlock Control block for the discovery/handshake region.

Types

	Name
using int	NativeHandle

Functions

	Name
size_t	ringBufferWriteAvailable(uint64_t writePos, uint64_t readPos, size_t bufferSize) Calculate available space in a ring buffer for writing.
size_t	ringBufferReadAvailable(uint64_t writePos, uint64_t readPos, size_t bufferSize) Calculate available data in a ring buffer for reading.
uint64_t	ringBufferAdvance(uint64_t pos, size_t amount, size_t bufferSize) Advance a ring buffer position.
uint32_t	getCurrentProcessId() Get current process ID (cross-platform).
uint64_t	generateSecurityToken() Generate a cryptographically random 64-bit token.
std::string	generateRandomHex(size_t length =16) Generate a random hex string for region names.

Attributes

	Name
uint32_t	SHM_VERSION Current protocol version.
uint32_t	SHM_MAGIC Magic number for control block validation (“ENTR” in little-endian).
size_t	MAX_REGION_NAME_LENGTH Maximum region name length.
NativeHandle	INVALID_HANDLE_VALUE_SHM
int	DEFAULT_WAIT_TIMEOUT_MS Timeout for wake/wait operations (ms).
size_t	DEFAULT_REGION_SIZE Default shared memory region size (4 MiB).
size_t	CONTROL_BLOCK_SIZE Control block size (256 bytes, cache-aligned).

Types Documentation

using NativeHandle

using EntropyEngine::Networking::SharedMemory::NativeHandle = int;

Functions Documentation

function ringBufferWriteAvailable

inline size_t ringBufferWriteAvailable(
    uint64_t writePos,
    uint64_t readPos,
    size_t bufferSize
)

Calculate available space in a ring buffer for writing.

Parameters:

• writePos Current write position (monotonic counter)
• readPos Current read position (monotonic counter)
• bufferSize Total buffer size

Return: Number of bytes available for writing

Uses monotonic 64-bit counters that wrap via natural overflow. The actual ring buffer position is computed as (counter % bufferSize) when accessing memory. This eliminates wrap-around edge case logic in availability calculations.

function ringBufferReadAvailable

inline size_t ringBufferReadAvailable(
    uint64_t writePos,
    uint64_t readPos,
    size_t bufferSize
)

Calculate available data in a ring buffer for reading.

Parameters:

• writePos Current write position (monotonic counter)
• readPos Current read position (monotonic counter)
• bufferSize Total buffer size (unused, kept for API consistency)

Return: Number of bytes available for reading

Uses monotonic 64-bit counters. The difference between write and read positions gives the number of unread bytes directly.

function ringBufferAdvance

inline uint64_t ringBufferAdvance(
    uint64_t pos,
    size_t amount,
    size_t bufferSize
)

Advance a ring buffer position.

Parameters:

• pos Current position (monotonic counter)
• amount Amount to advance
• bufferSize Total buffer size (unused, kept for API consistency)

Return: New position (monotonic counter)

Simply adds the amount to the monotonic counter. Actual memory access should use (pos % bufferSize) to get the ring buffer index.

function getCurrentProcessId

uint32_t getCurrentProcessId()

Get current process ID (cross-platform).

Return: Process ID as uint32_t

function generateSecurityToken

inline uint64_t generateSecurityToken()

Generate a cryptographically random 64-bit token.

Return: Random token for connection validation

function generateRandomHex

inline std::string generateRandomHex(
    size_t length =16
)

Generate a random hex string for region names.

Parameters:

• length Number of hex characters (default 16 = 64 bits)

Return: Random hex string

Attributes Documentation

variable SHM_VERSION

static uint32_t SHM_VERSION = 1;

Current protocol version.

variable SHM_MAGIC

static uint32_t SHM_MAGIC = 0x52544E45;

Magic number for control block validation (“ENTR” in little-endian).

variable MAX_REGION_NAME_LENGTH

static size_t MAX_REGION_NAME_LENGTH = 256;

Maximum region name length.

variable INVALID_HANDLE_VALUE_SHM

static NativeHandle INVALID_HANDLE_VALUE_SHM = -1;

variable DEFAULT_WAIT_TIMEOUT_MS

static int DEFAULT_WAIT_TIMEOUT_MS = 100;

Timeout for wake/wait operations (ms).

variable DEFAULT_REGION_SIZE

static size_t DEFAULT_REGION_SIZE = 4ull * 1024ull * 1024ull;

Default shared memory region size (4 MiB).

variable CONTROL_BLOCK_SIZE

static size_t CONTROL_BLOCK_SIZE = 256;

Control block size (256 bytes, cache-aligned).

---

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