Checked split-region planning for reader_vmem cache RAM. More...

#include <stddef.h>
#include <stdint.h>
#include "reader_vmem_internal.h"

Include dependency graph for reader_vmem_workspace.c:

Functions
static RA8_INTERNAL bool	internal_size_mul (size_t left, size_t right, size_t *result)
	Multiply two sizes without wrapping.
static RA8_INTERNAL bool	internal_region (size_t cursor, size_t bytes, size_t offset, size_t next)
	Place one maximally aligned region after a prior high-water.
bool	priv_rv_workspace_require (uint32_t budget, rv_workspace_need_t *need)
	Query exact split-region requirements for one frame budget.
static RA8_INTERNAL bool	internal_region_valid (size_t offset, size_t bytes, size_t total)
	Check one region lies wholly inside a workspace high-water.
bool	priv_rv_workspace_bind (void backing, size_t backing_bytes, const rv_workspace_need_t need, rv_workspace_t *workspace)
	Bind typed cache views into an aligned caller-owned backing.

Detailed Description

Checked split-region planning for reader_vmem cache RAM.

The planner has no storage ownership and no process-global state. Distinct callers may bind distinct backings concurrently; the standalone CLI chooses one explicit composition-root BSS backing for its single cache instance.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file reader_vmem_workspace.c.

Function Documentation

◆ internal_region()

RA8_INTERNAL bool internal_region	(	size_t	cursor,
		size_t	bytes,
		size_t *	offset,
		size_t *	next )

static

Place one maximally aligned region after a prior high-water.

Computes bounded padding, aligned start, and next high-water without overflow.

Parameters

[in]	cursor	Previous one-past high-water offset.
[in]	bytes	Region byte count.
[out]	offset	Receives aligned region start.
[out]	next	Receives one-past region end.

Returns: Whether both output coordinates are representable.

Return values

true	Outputs describe a complete aligned region.
false	Padding or end arithmetic would overflow.

Precondition: offset and next are non-null and writable.; Maximum fundamental alignment is non-zero.

Postcondition: Success initializes both outputs with offset <= next.; Failure leaves both outputs unchanged.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 62 of file reader_vmem_workspace.c.

References RA8_INTERNAL.

Referenced by priv_rv_workspace_require().

◆ internal_region_valid()

RA8_INTERNAL bool internal_region_valid	(	size_t	offset,
		size_t	bytes,
		size_t	total )

static

Check one region lies wholly inside a workspace high-water.

Uses subtractive bounds checks and enforces maximum alignment.

Parameters

[in]	offset	Region start relative to backing.
[in]	bytes	Region byte count.
[in]	total	Workspace high-water byte count.

Returns: Whether the half-open region is aligned and wholly bounded.

Return values

true	Region fits within [0,total) or is a valid empty endpoint.
false	Offset, length, or alignment is invalid.

Precondition: All values are offsets into one conceptual caller backing.; Maximum fundamental alignment is non-zero.

Postcondition: No state changes.; No pointer is formed or dereferenced.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 115 of file reader_vmem_workspace.c.

References RA8_INTERNAL.

Referenced by priv_rv_workspace_bind().

◆ internal_size_mul()

RA8_INTERNAL bool internal_size_mul	(	size_t	left,
		size_t	right,
		size_t *	result )

static

Multiply two sizes without wrapping.

Performs the division guard before the only multiplication.

Parameters

[in]	left	First factor.
[in]	right	Second factor.
[out]	result	Receives the exact product on success.

Returns: Whether the product is representable by size_t.

Return values

true	Exact product was stored.
false	Product would overflow.

Precondition: result is non-null and writable.; Both factors may be any representable size.

Postcondition: Success initializes result exactly once.; Failure leaves result unchanged.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 36 of file reader_vmem_workspace.c.

References RA8_INTERNAL.

Referenced by priv_rv_workspace_require().

◆ priv_rv_workspace_bind()

bool priv_rv_workspace_bind	(	void *	backing,
		size_t	backing_bytes,
		const rv_workspace_need_t *	need,
		rv_workspace_t *	workspace )

nodiscard

Bind typed cache views into an aligned caller-owned backing.

Definition at line 121 of file reader_vmem_workspace.c.

References rv_workspace_need_t::bucket_bytes, rv_workspace_need_t::bucket_offset, rv_workspace_need_t::frame_bytes, rv_workspace_need_t::frame_offset, internal_region_valid(), rv_workspace_need_t::key_bytes, rv_workspace_need_t::key_offset, rv_workspace_need_t::meta_bytes, rv_workspace_need_t::meta_offset, and rv_workspace_need_t::total_bytes.

Referenced by internal_prepare().

◆ priv_rv_workspace_require()

bool priv_rv_workspace_require	(	uint32_t	budget,
		rv_workspace_need_t *	need )

nodiscard

Query exact split-region requirements for one frame budget.

Definition at line 75 of file reader_vmem_workspace.c.

References rv_workspace_need_t::bucket_bytes, rv_workspace_need_t::bucket_offset, rv_workspace_need_t::frame_bytes, rv_workspace_need_t::frame_offset, internal_region(), internal_size_mul(), k_rv_bucket_count, k_rv_frame_bytes, rv_workspace_need_t::key_bytes, rv_workspace_need_t::key_offset, rv_workspace_need_t::meta_bytes, rv_workspace_need_t::meta_offset, and rv_workspace_need_t::total_bytes.

Referenced by internal_prepare().

Functions

Detailed Description

Function Documentation

◆ internal_region()

◆ internal_region_valid()

◆ internal_size_mul()

◆ priv_rv_workspace_bind()

◆ priv_rv_workspace_require()