Buffer Class Reference

Generic memory buffer descriptor with alignment and memory space support. More...

#include <buffer.h>

Public Types
using	Ptr = SharedPtr< Buffer >
	Shared pointer type for Buffer.
using	List = promeki::List< Buffer >
	List of Buffer values.
using	PtrList = promeki::List< Ptr >
	List of shared Buffer pointers.

Public Member Functions
	Buffer ()=default
	Constructs an invalid (empty) buffer.
	Buffer (size_t sz, size_t an=DefaultAlign, const MemSpace &ms=MemSpace::Default)
	Allocates a buffer of the given size.
	Buffer (void *p, size_t sz, size_t an=0, bool own=false, const MemSpace &ms=MemSpace::Default)
	Wraps an existing memory pointer as a buffer.
	Buffer (const Buffer &o)
	Copy constructor.
Buffer &	operator= (const Buffer &o)
	Copy assignment operator. Performs a deep copy.
	Buffer (Buffer &&o) noexcept
	Move constructor. Transfers ownership from the source buffer.
Buffer &	operator= (Buffer &&o) noexcept
	Move assignment operator. Transfers ownership from the source buffer.
	~Buffer ()
	Destructor. Releases owned memory.
bool	isValid () const
	Returns true if the buffer has been allocated or assigned memory.
void *	data () const
	Returns a pointer to the buffer data.
void *	odata () const
	Returns the original allocation pointer.
size_t	size () const
	Returns the logical content size in bytes.
void	setSize (size_t s) const
	Sets the logical content size.
size_t	availSize () const
	Returns the available space from data() to the end of the allocation.
size_t	allocSize () const
	Returns the total allocation size in bytes.
size_t	align () const
	Returns the alignment of the buffer in bytes.
const MemSpace &	memSpace () const
	Returns the memory space this buffer was allocated from.
const MemAllocation &	allocation () const
	Returns the underlying allocation descriptor.
void	shiftData (size_t bytes)
	Shifts the data pointer forward from the allocation base.
bool	isHostAccessible () const
	Returns true if the buffer memory is directly accessible from the host CPU.
void	setOwnershipEnabled (bool val)
	Enables or disables ownership of the underlying memory.
Error	fill (char value) const
	Fills the entire buffer with the given byte value.
Error	copyFrom (const void *src, size_t bytes, size_t offset=0) const
	Copies data from an external source into the buffer.

Static Public Member Functions
static size_t	getPageSize ()
	Returns the system memory page size in bytes.

Static Public Attributes
static const size_t	DefaultAlign
	Default memory alignment in bytes.

Detailed Description

Generic memory buffer descriptor with alignment and memory space support.

Buffer is a uniform tracking object for contiguous memory regions that may reside in different address spaces: local system RAM, GPU device memory, or even remote memory on another machine (e.g. RDMA). It does not assume the memory is host-accessible — use isHostAccessible() before dereferencing data(). All memory operations (allocation, release, copy, fill) are delegated through the buffer's MemSpace, allowing each memory space to provide appropriate implementations.

Allocation and ownership

Buffers can be allocated from any MemSpace, or can wrap existing memory pointers without taking ownership. Owned buffers are released through their MemSpace on destruction. The MemSpace's release implementation handles any space-specific cleanup (e.g. SystemSecure performs secure zeroing and page unlocking before freeing).

Buffer sizes

Buffer tracks three distinct sizes:

• allocSize() — the total allocation size, always constant.
• availSize() — the usable space from data() to the end of the allocation (allocSize minus any data shift). This is the maximum amount of content the buffer can hold at the current shift.
• size() — the logical content size, tracking how many bytes of meaningful data are in the buffer. Defaults to 0 after allocation (the buffer has capacity but no content yet). Set via setSize().

Data shifting

The shiftData() method offsets the user-visible data pointer from the allocation base. This is primarily used for O_DIRECT I/O, where the underlying allocation must be page-aligned but the actual content starts at some offset within that allocation. The shift is always relative to the allocation base (not accumulating). After a shift, availSize() returns the remaining usable bytes and size() is reset to 0. Calling shiftData(0) resets the view to the base.

Copy semantics

Copying a buffer performs a deep copy through the MemSpace's copy operation, preserving any data shift offset. The copy inherits the source's MemSpace, so copies of a SystemSecure buffer remain secure. For memory spaces where deep copy is expensive or impossible (large GPU framebuffers, remote RDMA regions), use Buffer::Ptr for shared ownership instead.

Shared ownership

When shared ownership is needed, use Buffer::Ptr (SharedPtr<Buffer>). This is the recommended approach for large buffers or buffers in

Example

// Allocate a 4 KB page-aligned buffer
Buffer buf(4096);
buf.fill(0);
buf.setSize(128);  // 128 bytes of content written
 
// Shared ownership for zero-copy passing
Buffer::Ptr shared = Buffer::Ptr::create(1920 * 1080 * 4);
 
// Copy external data into the buffer
const char *src = "hello";
buf.copyFrom(src, 5);

non-host-accessible memory spaces, as it avoids deep copies.

Constructor & Destructor Documentation

Buffer() [1/3]

Buffer::Buffer ( size_t  sz, size_t  an = DefaultAlign, const MemSpace &  ms = MemSpace::Default  )

inline

Allocates a buffer of the given size.

Parameters

sz	Size in bytes to allocate.
an	Alignment in bytes (defaults to DefaultAlign).
ms	Memory space to allocate from.

Buffer() [2/3]

Buffer::Buffer ( void *  p, size_t  sz, size_t  an = 0, bool  own = false, const MemSpace &  ms = MemSpace::Default  )

inline

Wraps an existing memory pointer as a buffer.

Parameters

p	Pointer to existing memory.
sz	Size of the memory region in bytes.
an	Alignment of the pointer (0 if unknown).
own	If true, the buffer takes ownership and will free the memory on destruction.
ms	Memory space the pointer belongs to.

Buffer() [3/3]

Buffer::Buffer ( const Buffer &  o )

inline

Copy constructor.

Performs a deep copy of the buffer data, including any data shift offset and the logical size.

Member Function Documentation

align()

size_t Buffer::align ( ) const

inline

Returns the alignment of the buffer in bytes.

Returns

The alignment value.

allocation()

const MemAllocation & Buffer::allocation ( ) const

inline

Returns the underlying allocation descriptor.

Returns

A const reference to the MemAllocation.

allocSize()

size_t Buffer::allocSize ( ) const

inline

Returns the total allocation size in bytes.

This always returns the full allocation size regardless of any shiftData() calls or the logical content size.

Returns

The allocation size.

availSize()

size_t Buffer::availSize ( ) const

inline

Returns the available space from data() to the end of the allocation.

This is the maximum number of bytes that can be stored starting from data(). Equal to allocSize() minus any data shift.

Returns

The available buffer space in bytes.

copyFrom()

Error Buffer::copyFrom	(	const void *	src,
		size_t	bytes,
		size_t	offset = 0
	)		const

Copies data from an external source into the buffer.

Copies bytes from src into the buffer starting at offset bytes from data(). The buffer must be valid and host-accessible, and offset + bytes must not exceed availSize().

Parameters

src	Pointer to the source data.
bytes	Number of bytes to copy.
offset	Destination offset from data() (default 0).

Returns

Error::Ok on success, or an appropriate error code.

data()

void * Buffer::data ( ) const

inline

Returns a pointer to the buffer data.

Returns

The current data pointer (may be shifted from the original allocation).

fill()

Error Buffer::fill ( char  value ) const

inline

Fills the entire buffer with the given byte value.

Parameters

value

The byte value to fill with.

Returns

Error::Ok on success, or an error on failure.

getPageSize()

static size_t Buffer::getPageSize ( )

static

Returns the system memory page size in bytes.

Returns

The page size.

isHostAccessible()

bool Buffer::isHostAccessible ( ) const

inline

Returns true if the buffer memory is directly accessible from the host CPU.

Returns

True for system memory, false for device or remote memory.

isValid()

bool Buffer::isValid ( ) const

inline

Returns true if the buffer has been allocated or assigned memory.

Returns

true if the internal data pointer is non-null.

memSpace()

const MemSpace & Buffer::memSpace ( ) const

inline

Returns the memory space this buffer was allocated from.

Returns

A const reference to the MemSpace.

odata()

void * Buffer::odata ( ) const

inline

Returns the original allocation pointer.

Unlike data(), this always points to the start of the allocated region regardless of any shiftData() calls. This is the pointer that was returned by the MemSpace allocator.

Returns

The original allocation pointer.

setOwnershipEnabled()

void Buffer::setOwnershipEnabled ( bool  val )

inline

Enables or disables ownership of the underlying memory.

Parameters

val	If true, the buffer will free memory on destruction; if false, it will not.

setSize()

void Buffer::setSize ( size_t  s ) const

inline

Sets the logical content size.

Indicates how many bytes of meaningful data are in the buffer, starting from data(). The value must not exceed availSize().

Parameters

s	The new logical content size.

shiftData()

void Buffer::shiftData ( size_t  bytes )

inline

Shifts the data pointer forward from the allocation base.

Sets the data pointer to allocation base + bytes, creating a sub-buffer view. The shift is always relative to the original allocation pointer, not the current data pointer.

Parameters

bytes

Number of bytes from the allocation base.

size()

size_t Buffer::size ( ) const

inline

Returns the logical content size in bytes.

This is the user-set content size, tracking how many bytes of meaningful data are in the buffer. Defaults to 0 after allocation (the buffer has capacity but no content yet). Set via setSize().

Returns

The logical content size.

---

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

• include/promeki/core/buffer.h