Buffers

Refcounted byte container that holds an ordered list of RMem chunks. More...

Macros
#define	r_buffer_ref   r_ref_ref
	Take a reference (alias for r_ref_ref).
#define	r_buffer_unref   r_ref_unref
	Drop a reference (alias for r_ref_unref).

Typedefs
typedef struct RBuffer	RBuffer
	Opaque, refcounted multi-segment byte buffer.

Construction
RBuffer *	r_buffer_new (void)
	Empty buffer with no segments.
RBuffer *	r_buffer_new_alloc (RMemAllocator *allocator, rsize allocsize, const RMemAllocationParams *params)
	Buffer with one fresh segment allocated by allocator.
RBuffer *	r_buffer_new_wrapped (RMemFlags flags, rpointer data, rsize allocsize, rsize size, rsize offset, rpointer user, RDestroyNotify usernotify)
	Wrap an externally-owned buffer.
static RBuffer *	r_buffer_new_take (rpointer data, rsize size)
	Wrap data and free it with r_free when the segment dies. Ownership transfers unconditionally: data is freed even if creation fails, so the caller must not free it on a NULL return.
static RBuffer *	r_buffer_new_dup (rconstpointer data, rsize size)
	Allocate-and-copy data, returning a wrapping buffer.
RBuffer *	r_buffer_view (RBuffer *from, rsize offset, rssize size)
	Zero-copy view of size bytes from from at offset.
RBuffer *	r_buffer_copy (RBuffer *from, rsize offset, rssize size)
	Deep copy of size bytes from from at offset.

Inspection
rboolean	r_buffer_is_all_writable (const RBuffer *buffer)
	TRUE iff every segment is writable (refcount 1, no read-only flag).
rboolean	r_buffer_mem_is_writable (const RBuffer *buffer, ruint idx)
	TRUE iff the segment at idx is writable.
rsize	r_buffer_get_size (const RBuffer *buffer)
	Total usable byte count summed over all segments.
rsize	r_buffer_get_allocsize (const RBuffer *buffer)
	Total allocated byte count summed over all segments.
rsize	r_buffer_get_offset (const RBuffer *buffer)
	Sum of the per-segment leading offsets.

Segment manipulation
ruint	r_buffer_mem_count (const RBuffer *buffer)
	Number of RMem segments in buffer.
rboolean	r_buffer_mem_insert (RBuffer *buffer, RMem *mem, ruint idx)
	Insert mem at segment position idx.
rboolean	r_buffer_mem_prepend (RBuffer *buffer, RMem *mem)
	Prepend mem as the new first segment.
rboolean	r_buffer_mem_append (RBuffer *buffer, RMem *mem)
	Append mem as the new last segment.
rboolean	r_buffer_mem_replace_range (RBuffer *buffer, ruint idx, int mem_count, RMem *mem) R_ATTR_WARN_UNUSED_RESULT
	Replace mem_count segments starting at idx with mem.
RMem *	r_buffer_mem_peek (RBuffer *buffer, ruint idx) R_ATTR_WARN_UNUSED_RESULT
	Peek at the segment at idx (caller takes a reference).
RMem *	r_buffer_mem_remove (RBuffer *buffer, ruint idx) R_ATTR_WARN_UNUSED_RESULT
	Remove and return the segment at idx.
void	r_buffer_mem_clear (RBuffer *buffer)
	Drop every segment from buffer.
rboolean	r_buffer_mem_find (const RBuffer *buffer, rsize offset, rssize size, ruint *idx, ruint *count, rsize *first_offset, rsize *last_size)
	Locate the segments that cover size bytes starting at offset.
#define	r_buffer_mem_replace(buf, idx, mem)    r_buffer_mem_replace_range (buf, idx, 1, mem)
	Replace one segment at idx with mem.
#define	r_buffer_mem_replace_all(buf, mem)    r_buffer_mem_replace_range (buf, 0, -1, mem)
	Replace every segment with a single mem.

Append, merge and replace
rboolean	r_buffer_append_mem_from_buffer (RBuffer *buffer, RBuffer *from)
	Append all of from's segments onto buffer (zero-copy).
rboolean	r_buffer_append_view (RBuffer *buffer, RBuffer *from, rsize offset, rssize size)
	Append a view of from's byte range onto buffer (zero-copy).
RBuffer *	r_buffer_merge_take (RBuffer *a,...) R_ATTR_WARN_UNUSED_RESULT
	Merge a NULL-terminated list of buffers; takes ownership of every input.
RBuffer *	r_buffer_merge_takev (RBuffer *a, va_list args) R_ATTR_WARN_UNUSED_RESULT
	va_list variant of r_buffer_merge_take.
RBuffer *	r_buffer_merge_take_array (RBuffer **a, ruint count) R_ATTR_WARN_UNUSED_RESULT
	Array variant of r_buffer_merge_take.
RBuffer *	r_buffer_replace_byte_range (RBuffer *buffer, rsize offset, rssize size, RBuffer *from) R_ATTR_WARN_UNUSED_RESULT
	Splice from into buffer over the byte range [offset, offset + size).

Resize
rboolean	r_buffer_resize (RBuffer *buffer, rsize offset, rsize size)
	Adjust buffer to view size bytes starting at offset.
rboolean	r_buffer_shrink (RBuffer *buffer, rsize size)
	Truncate buffer down to size bytes.
#define	r_buffer_set_size(buf, size)   r_buffer_shrink (buf, size)
	Alias for r_buffer_shrink.

Mapping (contiguous access)
rboolean	r_buffer_map_mem_range (RBuffer *buffer, ruint idx, int mem_count, RMemMapInfo *info, RMemMapFlags flags)
	Map a segment range. If the range spans multiple segments a temporary contiguous copy is built; r_buffer_unmap writes it back when needed.
rboolean	r_buffer_map_byte_range (RBuffer *buffer, rsize offset, rssize size, RMemMapInfo *info, RMemMapFlags flags)
	Map a byte range; offsets / sizes can straddle segment boundaries.
rboolean	r_buffer_unmap (RBuffer *buffer, RMemMapInfo *info)
	Release a mapping; commits writes if the map was writable.
#define	r_buffer_map(buf, info, flags)    r_buffer_map_mem_range (buf, 0, -1, info, flags)
	Map the entire buffer with flags.

Bulk copy
rsize	r_buffer_fill (RBuffer *buffer, rsize offset, rconstpointer src, rsize size)
	Copy size bytes from src into buffer at offset.
rsize	r_buffer_extract (RBuffer *buffer, rsize offset, rpointer dst, rssize size)
	Copy size bytes (or -1 for all) from buffer at offset into dst.
rpointer	r_buffer_extract_dup (RBuffer *buffer, rsize offset, rssize size, rsize *dstsize)
	Allocate-and-copy size bytes from buffer.
int	r_buffer_cmp (RBuffer *buf1, rsize offset1, RBuffer *buf2, rsize offset2, rsize size)
	memcmp across two buffers.
int	r_buffer_memcmp (RBuffer *buffer, rsize offset, rconstpointer mem, rsize size)
	memcmp between a buffer and a flat byte array.
rsize	r_buffer_memset (RBuffer *buffer, rsize offset, ruint8 val, rsize size)
	memset val into buffer starting at offset.
#define	r_buffer_extract_dup_all(buf, dstsize)   r_buffer_extract_dup (buf, 0, -1, dstsize)
	r_buffer_extract_dup over the whole buffer.

Detailed Description

Refcounted byte container that holds an ordered list of RMem chunks.

Inspired by GStreamer's GstBuffer: a single logical byte stream composed of multiple RMem segments, each backed by a possibly different RMemAllocator. Operations like r_buffer_view, r_buffer_merge_take and r_buffer_append_view manipulate the segment list without copying the underlying memory when possible.

To read or write contiguous bytes, map a range with r_buffer_map (or one of the _range variants) and pair with r_buffer_unmap. For one-shot scalar copies use r_buffer_fill / r_buffer_extract.

Function Documentation

r_buffer_extract_dup()

rpointer r_buffer_extract_dup	(	RBuffer *	buffer,
		rsize	offset,
		rssize	size,
		rsize *	dstsize
	)

Allocate-and-copy size bytes from buffer.

Parameters

buffer	Source buffer.
offset	Starting offset.
size	Byte count to extract, or -1 for the rest.
dstsize	Optional out-pointer that receives the actual byte count.

r_buffer_mem_find()

rboolean r_buffer_mem_find	(	const RBuffer *	buffer,
		rsize	offset,
		rssize	size,
		ruint *	idx,
		ruint *	count,
		rsize *	first_offset,
		rsize *	last_size
	)

Locate the segments that cover size bytes starting at offset.

Sets idx to the first covering segment, count to how many are needed, first_offset to the byte offset inside the first segment, and last_size to the bytes used inside the last.

r_buffer_mem_replace_range()

rboolean r_buffer_mem_replace_range	(	RBuffer *	buffer,
		ruint	idx,
		int	mem_count,
		RMem *	mem
	)

Replace mem_count segments starting at idx with mem.

Parameters

buffer	Target buffer.
idx	Position of the first segment to replace.
mem_count	Number of segments to replace, or -1 for all.
mem	Replacement segment.

r_buffer_new_wrapped()

RBuffer * r_buffer_new_wrapped	(	RMemFlags	flags,
		rpointer	data,
		rsize	allocsize,
		rsize	size,
		rsize	offset,
		rpointer	user,
		RDestroyNotify	usernotify
	)

Wrap an externally-owned buffer.

Parameters

flags	Memory flags to apply to the wrapped segment.
data	Pointer to the user-owned bytes.
allocsize	Size of the allocation backing data.
size	Initial usable size (<= allocsize).
offset	Initial offset into data.
user	Opaque pointer forwarded to usernotify.
usernotify	Destructor called when the wrapping segment is freed; receives user.

usernotify runs exactly once whether the buffer is created or creation fails (so a non-NULL usernotify must not be paired with the caller freeing data on a NULL return).

r_buffer_replace_byte_range()

RBuffer * r_buffer_replace_byte_range	(	RBuffer *	buffer,
		rsize	offset,
		rssize	size,
		RBuffer *	from
	)

Splice from into buffer over the byte range [offset, offset + size).

Returns

A new buffer; the inputs are left unchanged.