Lock-free single-producer single-consumer shared memory ring buffer. More...

#include <spsc_shm.hpp>

Public Member Functions
	SpscShm (SpscShm &&other) noexcept

SpscShm &	operator= (SpscShm &&other) noexcept

	SpscShm (const SpscShm &)=delete

SpscShm &	operator= (const SpscShm &)=delete

	~SpscShm ()

uint64_t	available () const

uint64_t	capacity () const

void *	claim (size_t want, uint32_t timeout_ns)
	Claim contiguous space in the ring buffer (blocks until available)

void	publish (size_t n)
	Publish n bytes previously claimed.

void *	peek (size_t want, uint32_t timeout_ns)
	Peek contiguous readable region (blocks until available)

void	release (size_t n)
	Release n bytes previously peeked.

void	wakeup_all ()
	Wake all blocked threads (for graceful shutdown)

bool	wait_for_data (size_t need, uint32_t spin_ns)

bool	wait_for_space (size_t need, uint32_t spin_ns)

void	debug_dump (const char *prefix) const
	Dump internal ring buffer state for debugging.

Static Public Member Functions
static SpscShm	create (const std::string &name, size_t min_capacity)
	Create a new SPSC ring buffer.

static SpscShm	connect (const std::string &name)
	Connect to existing SPSC ring buffer.

static bool	unlink (const std::string &name)
	Unlink shared memory object (cleanup after close)

Private Member Functions
	SpscShm (int fd, size_t map_len, SpscCtrl ctrl, uint8_t buf)

Private Attributes
int	fd_ = -1

size_t	map_len_ = 0

SpscCtrl *	ctrl_ = nullptr

uint8_t *	buf_ = nullptr

bool	previous_had_data_ = false

bool	previous_had_space_ = false

Detailed Description

Lock-free single-producer single-consumer shared memory ring buffer.

Provides zero-copy message passing between processes using shared memory. Uses futex for efficient blocking when empty/full.

CRITICAL USAGE REQUIREMENT: Each claim(n)/publish(n) pair by the producer MUST be perfectly matched by a corresponding peek(n)/release(n) pair by the consumer, with the EXACT same sizes.

This is because the wrapping logic is completely stateless - it decides whether to wrap based solely on whether the requested size fits in the remaining space before the end of the buffer. If the producer and consumer use different sizes, they will make inconsistent wrap decisions and data corruption will occur.

CORRECT usage example (framed messages): Producer: Consumer: claim(4), publish(4) <—> peek(4), release(4) // length prefix claim(msg_len), publish(msg_len) <—> peek(msg_len), release(msg_len) // message data

Definition at line 70 of file spsc_shm.hpp.

Constructor & Destructor Documentation

◆ SpscShm() [1/3]

bb::ipc::SpscShm::SpscShm ( SpscShm && other )

noexcept

Definition at line 48 of file spsc_shm.cpp.

◆ SpscShm() [2/3]

bb::ipc::SpscShm::SpscShm ( const SpscShm & )

delete

◆ ~SpscShm()

bb::ipc::SpscShm::~SpscShm ( )

Definition at line 86 of file spsc_shm.cpp.

◆ SpscShm() [3/3]

bb::ipc::SpscShm::SpscShm	(	int	fd,
		size_t	map_len,
		SpscCtrl *	ctrl,
		uint8_t *	buf
	)

private

Definition at line 41 of file spsc_shm.cpp.

Member Function Documentation

◆ available()

uint64_t bb::ipc::SpscShm::available ( ) const

Definition at line 197 of file spsc_shm.cpp.

◆ capacity()

uint64_t bb::ipc::SpscShm::capacity ( ) const

inline

Definition at line 105 of file spsc_shm.hpp.

◆ claim()

void * bb::ipc::SpscShm::claim	(	size_t	want,
		uint32_t	timeout_ns
	)

Claim contiguous space in the ring buffer (blocks until available)

Producer API: claim() and publish() must be used in pairs

Parameters

want	Number of bytes to claim
timeout_ns	Timeout in nanoseconds

Returns: Pointer to claimed space, or nullptr on timeout

IMPORTANT: The size passed to claim(want) must exactly match the size passed to the corresponding peek(want) call by the consumer. Otherwise wrap decisions will be inconsistent.

Definition at line 204 of file spsc_shm.cpp.

◆ connect()

SpscShm bb::ipc::SpscShm::connect ( const std::string & name )

static

Connect to existing SPSC ring buffer.

Parameters

name	Shared memory object name

Exceptions

std::runtime_error if connection fails

Definition at line 157 of file spsc_shm.cpp.

◆ create()

SpscShm bb::ipc::SpscShm::create	(	const std::string &	name,
		size_t	min_capacity
	)

static

Create a new SPSC ring buffer.

Parameters

name	Shared memory object name (without /dev/shm prefix)
min_capacity	Minimum capacity (rounded up to power of 2)

Exceptions

std::runtime_error if creation fails

Definition at line 96 of file spsc_shm.cpp.

◆ debug_dump()

void bb::ipc::SpscShm::debug_dump ( const char * prefix ) const

Dump internal ring buffer state for debugging.

Parameters

prefix Prefix string for the debug output (e.g., "Client REQ" or "Server RESP")

Definition at line 527 of file spsc_shm.cpp.

◆ operator=() [1/2]

SpscShm & bb::ipc::SpscShm::operator= ( const SpscShm & )

delete

◆ operator=() [2/2]

SpscShm & bb::ipc::SpscShm::operator= ( SpscShm && other )

noexcept

Definition at line 60 of file spsc_shm.cpp.

◆ peek()

void * bb::ipc::SpscShm::peek	(	size_t	want,
		uint32_t	timeout_ns
	)

Peek contiguous readable region (blocks until available)

Consumer API: peek() and release() must be used in pairs

Parameters

want	Number of bytes to peek
timeout_ns	Timeout in nanoseconds

Returns: Pointer to readable data, or nullptr on timeout

IMPORTANT: The size passed to peek(want) must exactly match the size passed to the corresponding claim(want) call by the producer. Otherwise wrap decisions will be inconsistent.

Definition at line 254 of file spsc_shm.cpp.

◆ publish()

void bb::ipc::SpscShm::publish ( size_t n )

Publish n bytes previously claimed.

Parameters

n	Number of bytes to publish (must match what was claimed)

IMPORTANT: The size passed to publish(n) must exactly match the size passed to the corresponding release(n) call by the consumer. Otherwise wrap decisions will be inconsistent.

Definition at line 227 of file spsc_shm.cpp.

◆ release()

void bb::ipc::SpscShm::release ( size_t n )

Release n bytes previously peeked.

Parameters

n	Number of bytes to release (must match what was peeked)

IMPORTANT: The size passed to release(n) must exactly match the size passed to the corresponding publish(n) call by the producer. Otherwise wrap decisions will be inconsistent.

Definition at line 285 of file spsc_shm.cpp.

◆ unlink()

bool bb::ipc::SpscShm::unlink ( const std::string & name )

static

Unlink shared memory object (cleanup after close)

Parameters

name	Shared memory object name

Returns: true if successful, false otherwise

Definition at line 192 of file spsc_shm.cpp.

◆ wait_for_data()

bool bb::ipc::SpscShm::wait_for_data	(	size_t	need,
		uint32_t	spin_ns
	)

Definition at line 313 of file spsc_shm.cpp.

◆ wait_for_space()

bool bb::ipc::SpscShm::wait_for_space	(	size_t	need,
		uint32_t	spin_ns
	)

Definition at line 417 of file spsc_shm.cpp.

◆ wakeup_all()

void bb::ipc::SpscShm::wakeup_all ( )

Wake all blocked threads (for graceful shutdown)

Wakes both producers blocked on space and consumers blocked on data. Used for graceful shutdown of the communication channel.

Definition at line 521 of file spsc_shm.cpp.

Member Data Documentation

◆ buf_

uint8_t* bb::ipc::SpscShm::buf_ = nullptr

private

Definition at line 175 of file spsc_shm.hpp.

◆ ctrl_

SpscCtrl* bb::ipc::SpscShm::ctrl_ = nullptr

private

Definition at line 174 of file spsc_shm.hpp.

◆ fd_

int bb::ipc::SpscShm::fd_ = -1

private

Definition at line 172 of file spsc_shm.hpp.

◆ map_len_

size_t bb::ipc::SpscShm::map_len_ = 0

private

Definition at line 173 of file spsc_shm.hpp.

◆ previous_had_data_

bool bb::ipc::SpscShm::previous_had_data_ = false

private

Definition at line 176 of file spsc_shm.hpp.

◆ previous_had_space_

bool bb::ipc::SpscShm::previous_had_space_ = false

private

Definition at line 177 of file spsc_shm.hpp.

The documentation for this class was generated from the following files:

src/barretenberg/ipc/shm/spsc_shm.hpp
src/barretenberg/ipc/shm/spsc_shm.cpp

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SpscShm() [1/3]

◆ SpscShm() [2/3]

◆ ~SpscShm()

◆ SpscShm() [3/3]

Member Function Documentation

◆ available()

◆ capacity()

◆ claim()

◆ connect()

◆ create()

◆ debug_dump()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ peek()

◆ publish()

◆ release()

◆ unlink()

◆ wait_for_data()

◆ wait_for_space()

◆ wakeup_all()

Member Data Documentation

◆ buf_

◆ ctrl_

◆ fd_

◆ map_len_

◆ previous_had_data_

◆ previous_had_space_