NPRPC docs

class flat_buffer

C++

class flat_buffer

A flat buffer that can operate in two modes: 1. Owned mode: manages its own heap-allocated memory (like boost::beast::flat_buffer) 2. View mode: references external memory (e.g., shared memory ring buffer)

In view mode, the buffer provides a zero-copy view into shared memory. The interface is compatible with boost::beast::flat_buffer for seamless integration with existing marshalling code.

Memory Layout (owned mode): +------------------+------------------+------------------+ | [consumed] | [readable] | [writable] | +------------------+------------------+------------------+ ^ ^ ^ ^ buffer_ in_ out_ capacity_

Memory Layout (view mode): +------------------+------------------+ | [readable] | [extendable] | +------------------+------------------+ ^ ^ ^ view_base_ view_base_+size_ view_base_+max_size_

include/nprpc/flat_buffer.hpp:78

Constructors

flat_buffer() = default

Default constructor (owned mode, empty)

include/nprpc/flat_buffer.hpp:270

explicit flat_buffer(std::size_t initial_capacity)

Constructor with initial capacity (owned mode)

include/nprpc/flat_buffer.hpp:273

flat_buffer(std::uint8_t *base, std::size_t size, std::size_t max_size, const EndPoint *endpoint = nullptr)

View constructor - creates a zero-copy view into external memory

base
Pointer to external memory (e.g., shared memory)
size
Current readable size
max_size
Maximum size available for extension (for prepare())
endpoint
Optional endpoint for fallback buffer growth

include/nprpc/flat_buffer.hpp:284

flat_buffer(flat_buffer &&other) noexcept

Move constructor

include/nprpc/flat_buffer.hpp:296

flat_buffer(const flat_buffer &other)

Copy constructor (deep copy, always creates owned buffer). Attached descriptors are not copied.

include/nprpc/flat_buffer.hpp:369

Methods

std::uint32_t attach_fd(UniqueFd fd)

Attaches fd to the message and returns the index an fd field stores to name it.

include/nprpc/flat_buffer.hpp:531

std::uint32_t call_id() const noexcept

The request id this message must be sent with, so the caller can name the call later to cancel it. Zero lets the transport pick one; runtime use.

include/nprpc/flat_buffer.hpp:539

std::size_t capacity() const noexcept

Returns the current capacity

include/nprpc/flat_buffer.hpp:420

const_buffers_type cdata() const noexcept

Returns a const buffer representing the readable data (alias for compatibility)

include/nprpc/flat_buffer.hpp:448

void clear() noexcept

Clear all data

include/nprpc/flat_buffer.hpp:514

void clear_reservation() noexcept

Clear the write reservation (after commit or abandon)

include/nprpc/flat_buffer.hpp:708

void commit(std::size_t n) noexcept

Commit written bytes to readable area

include/nprpc/flat_buffer.hpp:476

void commit_read_if_needed()

Commit the read if this buffer is a view from a ReadView Call this after unmarshaling is complete to free ring buffer space

include/nprpc/flat_buffer.hpp:635

void consume(std::size_t n) noexcept

Consume bytes from the readable area

include/nprpc/flat_buffer.hpp:486

const_buffers_type data() const noexcept

Returns a const buffer representing the readable data

include/nprpc/flat_buffer.hpp:429

mutable_buffers_type data() noexcept

Returns a mutable buffer representing the writable area

include/nprpc/flat_buffer.hpp:438

std::uint8_t *data_ptr() noexcept

Get raw pointer to data (for compatibility with existing code)

include/nprpc/flat_buffer.hpp:674

const std::uint8_t *data_ptr() const noexcept

Get raw pointer to data (for compatibility with existing code).

include/nprpc/flat_buffer.hpp:683

static constexpr std::size_t default_initial_size() noexcept

Capacity an owned buffer starts with: 1 KiB.

include/nprpc/flat_buffer.hpp:762

void detach_view()

Convert from view mode to owned mode (makes a copy)

include/nprpc/flat_buffer.hpp:646

const EndPoint *endpoint() const noexcept

Get the endpoint associated with this buffer (for view mode)

include/nprpc/flat_buffer.hpp:692

std::vector<UniqueFd> &fds() noexcept

The attached descriptors, for the transport: it sends these alongside the bytes and fills them in on the receiving side.

include/nprpc/flat_buffer.hpp:560

const std::vector<UniqueFd> &fds() const noexcept

Not documented.

include/nprpc/flat_buffer.hpp:561

bool has_fd(std::uint32_t index) const noexcept

Whether index names a descriptor that is still attached.

include/nprpc/flat_buffer.hpp:553

bool has_pending_read() const noexcept

Check if this buffer has a pending read to commit

include/nprpc/flat_buffer.hpp:638

bool has_write_reservation() const noexcept

Check if this buffer has a pending write reservation

include/nprpc/flat_buffer.hpp:699

bool is_view_mode() const noexcept

Check if buffer is in view mode

include/nprpc/flat_buffer.hpp:568

std::size_t max_size() const noexcept

Returns the maximum possible size

include/nprpc/flat_buffer.hpp:411

mutable_buffers_type prepare(std::size_t n)

Prepare writable area of specified size Note: In view mode, if the requested size exceeds max_size, the buffer will gracefully convert to owned mode (copying existing data)

Returns Mutable buffer for writing

include/nprpc/flat_buffer.hpp:454

void release_write_view() noexcept

Drop a write-view into the ring after a successful commit_write. Leaves the buffer empty and in owned mode so a subsequent response can be stored without overwriting the send ring (or triggering a grow that tries to re-reserve).

include/nprpc/flat_buffer.hpp:722

void *reservation_channel() const noexcept

Opaque SharedMemoryChannel* that owns a pending write reservation

include/nprpc/flat_buffer.hpp:716

uint64_t reservation_write_idx() const noexcept

Get the slot_idx for reconstructing WriteReservation

include/nprpc/flat_buffer.hpp:702

void set_arena(impl::BumpArena *arena) noexcept

Associate a bump arena with this buffer for the upcoming sync call. Must be called before the first prepare(). The arena is not owned; it is the caller's responsibility to reset it at the next call entry.

include/nprpc/flat_buffer.hpp:643

void set_call_id(std::uint32_t id) noexcept

Sets call_id(); runtime use.

include/nprpc/flat_buffer.hpp:541

void set_view(std::uint8_t *base, std::size_t size, std::size_t max_size, const EndPoint *endpoint = nullptr, std::size_t write_idx = 0, bool has_reservation = false, void *reservation_channel = nullptr)

Create a view into shared memory

base
Pointer to shared memory region
size
Current data size
max_size
Maximum writable size
endpoint
Optional endpoint for fallback buffer growth
write_idx
Optional write index for WriteReservation tracking
has_reservation
reservation_channel

include/nprpc/flat_buffer.hpp:576

void set_view_from_read(const void *data, std::size_t size, void *ring_buffer, std::size_t read_idx)

Create a view from a ReadView (for zero-copy response reading)

data
size
ring_buffer
Pointer to the LockFreeRingBuffer (for commit_read)
read_idx
read_view
The ReadView from ring buffer

include/nprpc/flat_buffer.hpp:605

std::size_t size() const noexcept

Returns the size of the readable area

include/nprpc/flat_buffer.hpp:402

static void swap(flat_buffer &a, flat_buffer &b) noexcept

Swap two flat_buffer instances

a
First buffer
b
Second buffer

include/nprpc/flat_buffer.hpp:742

UniqueFd take_fd(std::uint32_t index) noexcept

Takes the descriptor at index out of the message. Empty if there is none there, or it was taken already.

include/nprpc/flat_buffer.hpp:545

Operators

flat_buffer &operator=(flat_buffer &&other) noexcept

Move assignment

include/nprpc/flat_buffer.hpp:329

flat_buffer &operator=(const flat_buffer &other)

Copy assignment

include/nprpc/flat_buffer.hpp:381

Type aliases

using const_buffers_type = boost::asio::const_buffer

Readable region, as Boost.Asio sees it.

include/nprpc/flat_buffer.hpp:82

using mutable_buffers_type = boost::asio::mutable_buffer

Writable region, as Boost.Asio sees it.

include/nprpc/flat_buffer.hpp:84