sys_sharemem.h File Reference

Named cross-process shared memory region. More...

#include <cstdint>
#include <memory>
#include <string>
#include "./macros.h"

Include dependency graph for sys_sharemem.h:

Go to the source code of this file.

Classes
class	vlink::SysSharemem
	Named cross-process shared memory backed by the OS IPC layer. More...

Namespaces
namespace	vlink

Detailed Description

Named cross-process shared memory region.

SysSharemem wraps the POSIX shared-memory API (shm_open + mmap) on Linux/macOS and the Win32 CreateFileMapping / MapViewOfFile API on Windows to provide a named shared memory region that multiple processes can map into their address space simultaneously.

Lifecycle:

1. Construct a SysSharemem object.
2. Creator process: call create(name, size) to allocate and map the region.
3. Peer processes: call attach(name) to map the existing region.
4. Access the raw memory via data().
5. Call detach(force) to unmap. If force is true, POSIX backends also unlink the backing object from the OS namespace.
6. The destructor calls detach() automatically with force == false.

Access modes:

Mode	Description
kReadOnly	Maps with PROT_READ (no write access)

| kReadWrite | Maps with PROT_READ | PROT_WRITE (default) |

Note

• POSIX shared-memory names must start with '/' (e.g., "/vlink_cam0"). On Windows any non-empty name is valid.
• Shared memory is not initialised to zero by create(). The caller must initialise the region before use.
• Concurrent access from multiple processes requires external synchronisation (e.g., SysSemaphore or a mutex in the shared region itself).
• size() returns 0 when not attached.

Example

// Process A (creator):
vlink::SysSharemem shm;
shm.create("/vlink_frame", 1024 * 1024);  // 1 MB
auto* frame = static_cast<FrameHeader*>(shm.data());
frame->seq = 0;
sem.release();  // signal Process B
 
// Process B (consumer):
vlink::SysSharemem shm;
shm.attach("/vlink_frame");
sem.acquire();
const auto* frame = static_cast<const FrameHeader*>(shm.data());
process_frame(*frame);