rmemallocator.h File Reference

Refcounted memory-chunk abstraction with allocator vtables. More...

#include <rlib/rtypes.h>
#include <rlib/rmem.h>
#include <rlib/rref.h>
#include <stdarg.h>

Go to the source code of this file.

Data Structures
struct	RMemAllocationParams
	Allocation-time constraints passed to r_mem_allocator_alloc and the merge / take helpers. More...
struct	RMemMapInfo
	Scope object carried by an active mapping. More...
struct	RMem
	Concrete layout of an RMem chunk. More...
struct	RMemAllocator
	Concrete layout of an RMemAllocator. More...

Macros
#define	R_MEM_MAP_RW   (R_MEM_MAP_READ | R_MEM_MAP_WRITE)
	Convenience: read + write access.
#define	R_MEM_ALLOCATOR_SYSTEM   "system"
	Name of the built-in system / heap allocator.
#define	R_MEM_MAP_INFO_INIT   { NULL, 0, 0, 0, NULL }
	Zero-init for an RMemMapInfo declared on the stack.
#define	r_mem_ref   r_ref_ref
	Acquire a new reference to an RMem.
#define	r_mem_unref   r_ref_unref
	Release a reference; frees the chunk when the last drops.
#define	r_mem_is_readonly(mem)   (mem->flags & R_MEM_FLAG_READONLY)
	TRUE if mem carries R_MEM_FLAG_READONLY.
#define	r_mem_is_writable(mem)   ((mem->flags & R_MEM_FLAG_READONLY) == 0)
	TRUE if mem can accept writes.
#define	r_mem_is_zero_prefixed(mem)   (mem->flags & R_MEM_FLAG_ZERO_PREFIXED)
	TRUE if mem carries R_MEM_FLAG_ZERO_PREFIXED.
#define	r_mem_is_zero_padded(mem)   (mem->flags & R_MEM_FLAG_ZERO_PADDED)
	TRUE if mem carries R_MEM_FLAG_ZERO_PADDED.
#define	r_mem_allocator_default()   r_mem_allocator_find (R_MEM_ALLOCATOR_SYSTEM)
	Convenience for the built-in system / heap allocator.
#define	r_mem_allocator_ref   r_ref_ref
	Acquire a new reference to an RMemAllocator.
#define	r_mem_allocator_unref   r_ref_unref
	Release a reference to an RMemAllocator.

Typedefs
typedef ruint32	RMemFlags
	Bitmask of RMemFlag values.
typedef ruint32	RMemMapFlags
	Bitmask of RMemMapFlag values.

Enumerations
enum	RMemFlag {   R_MEM_FLAG_NONE = 0 , R_MEM_FLAG_READONLY = (1 << 0) , R_MEM_FLAG_NO_VIEWS = (1 << 1) , R_MEM_FLAG_ZERO_PREFIXED = (1 << 2) ,   R_MEM_FLAG_ZERO_PADDED = (1 << 3) }
	Per-chunk flags carried on every RMem. More...
enum	RMemMapFlag { R_MEM_MAP_READ = (1 << 0) , R_MEM_MAP_WRITE = (1 << 1) , R_MEM_MAP_FLAG_LAST = (1 << 8) }
	Mapping-access flags passed to r_mem_map. More...

Functions
RMem *	r_mem_new_wrapped (RMemFlags flags, rpointer data, rsize allocsize, rsize size, rsize offset, rpointer user, RDestroyNotify usernotify) R_ATTR_WARN_UNUSED_RESULT
	Wrap an existing pointer in an RMem without copying.
static RMem *	r_mem_new_take (RMemFlags flags, rpointer data, rsize allocsize, rsize size, rsize offset)
	Wrap an existing heap allocation in an RMem and transfer ownership.
rboolean	r_mem_resize (RMem *mem, rsize offset, rsize size)
	Adjust the visible window inside mem.
rboolean	r_mem_map (RMem *mem, RMemMapInfo *info, RMemMapFlags flags)
	Open a scoped mapping over mem's bytes.
rboolean	r_mem_unmap (RMem *mem, RMemMapInfo *info)
	Close a mapping previously opened with r_mem_map.
RMem *	r_mem_copy (RMem *mem, rssize offset, rssize size) R_ATTR_WARN_UNUSED_RESULT
	Deep-copy a byte range from mem into a fresh RMem.
RMem *	r_mem_view (RMem *mem, rssize offset, rssize size) R_ATTR_WARN_UNUSED_RESULT
	Create an aliased view onto a byte range of mem.
RMem *	r_mem_merge (const RMemAllocationParams *params, RMem *a,...) R_ATTR_WARN_UNUSED_RESULT
	Concatenate two or more chunks into a fresh RMem.
RMem *	r_mem_mergev (const RMemAllocationParams *params, RMem *a, va_list args) R_ATTR_WARN_UNUSED_RESULT
	va_list variant of r_mem_merge.
RMem *	r_mem_merge_array (const RMemAllocationParams *params, RMem **mems, ruint count) R_ATTR_WARN_UNUSED_RESULT
	Array variant of r_mem_merge - mems is a count-long array of chunk pointers.
RMem *	r_mem_take (const RMemAllocationParams *params, RMem *a,...) R_ATTR_WARN_UNUSED_RESULT
	Concatenate chunks (as r_mem_merge) but unref the inputs.
RMem *	r_mem_takev (const RMemAllocationParams *params, RMem *a, va_list args) R_ATTR_WARN_UNUSED_RESULT
	va_list variant of r_mem_take.
RMem *	r_mem_take_array (const RMemAllocationParams *params, RMem **mems, ruint count) R_ATTR_WARN_UNUSED_RESULT
	Array variant of r_mem_take - consumes references in mems on success.
void	r_mem_init (RMem *mem, RDestroyNotify notify, RMemFlags flags, RMemAllocator *allocator, RMem *parent, rsize allocsize, rsize size, rsize alignmask, rsize offset)
	Allocator-implementation helper: populate an RMem's common fields and arm its destructor.
void	r_mem_clear (RMem *mem)
	Allocator-implementation helper: release the references an RMem holds (parent, allocator).
RMemAllocator *	r_mem_allocator_find (const rchar *name) R_ATTR_WARN_UNUSED_RESULT
	Look up a registered allocator by name.
void	r_mem_allocator_register (RMemAllocator *allocator)
	Register an allocator so it can be looked up by name.
RMem *	r_mem_allocator_alloc_full (RMemAllocator *allocator, rsize size, const RMemAllocationParams *params) R_ATTR_WARN_UNUSED_RESULT
	Allocate a new RMem chunk via allocator.
static RMem *	r_mem_allocator_alloc (RMemAllocator *allocator, RMemFlags flags, rsize size, rsize prefix, rsize padding, rsize alignmask)
	Convenience for r_mem_allocator_alloc_full with the params spelled out as individual arguments.

Detailed Description

Refcounted memory-chunk abstraction with allocator vtables.

RMem wraps a byte region (with allocsize total bytes plus a visible offset / size window) and routes operations through an RMemAllocator vtable - so the same client-side API works on heap memory, shared memory, GPU-mapped buffers, file mappings, etc. Each chunk carries flags (read-only, view-prohibited, zero- prefixed / -padded) that the high-level helpers honour.

Allocators are looked up by name (R_MEM_ALLOCATOR_SYSTEM is the default heap allocator). Custom allocators register themselves at init time and become discoverable via r_mem_allocator_find.

Reference counting: both RMem and RMemAllocator are RRef-based; use the _ref / _unref helpers.

Mapping: to read or write the underlying bytes, wrap accesses in r_mem_map / r_mem_unmap - the RMemMapInfo carries the data pointer plus the allocator-specific bookkeeping that unmap needs.

The implementation of RMem and RMemAllocator is heavily inspired by the GStreamer equivalents.