Read a page-cached object as a seekable byte stream (Layer 2 helper, #147/#151). More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"
#include "ra8_vmem.h"

Include dependency graph for ra8_vmem_stream.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ra8_vmem_stream_t
	Binds one page-cached object to the byte-stream read adapter. More...

Functions
ra8_err_t	ra8_vmem_stream_init (ra8_vmem_stream_t st, ra8_vmem_t vm, uint32_t object_id, uint64_t size)
	Bind a page-cached paged object to the byte-stream reader.
size_t	ra8_vmem_stream_read (void ctx, uint64_t offset, void buf, size_t len)
	Read len bytes at absolute offset through the page cache.

Detailed Description

Read a page-cached object as a seekable byte stream (Layer 2 helper, #147/#151).

Tag: [Ring 2 / Core] {World: NS}

A thin adapter that turns a ::ra8_vmem-cached paged object into a random-access byte-stream reader: ra8_vmem_stream_read serves an arbitrary (offset, len) span by paging the covering frames through the SLRU cache and copying out the requested bytes. Hot pages (re-read headers, indices) stay resident in the fixed frame pool; cold pages are re-fetched from the backing through the cache's loader. The resident set never exceeds the cache's fixed frame budget, independent of object size – so a multi-GB object is readable through a few tens of KiB of RAM.

The read function's signature (opaque ctx, absolute offset, bytes-read return) is deliberately generic so any streamed consumer can drive it. In particular it is call-compatible with ra8_epub_open_streamed()'s ra8_epub_stream_read_fn, which is how a large .epub on the SD card is opened without whole-file residency (#151): register the file as a ::ra8_vsource paged object, front it with a fixed ::ra8_vmem pool (the asserted RAM budget), and hand the resulting ra8_vmem_stream_read to the EPUB reader.

Zero allocation (NASA P10 Rule 3): all storage is the caller's ::ra8_vmem pool; this adapter holds at most one pinned frame at a time and copies through it.

Note: Not thread-safe; the reader serialises access.

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

Since: 0.1.0

Definition in file ra8_vmem_stream.h.

Function Documentation

◆ ra8_vmem_stream_init()

ra8_err_t ra8_vmem_stream_init	(	ra8_vmem_stream_t *	st,
		ra8_vmem_t *	vm,
		uint32_t	object_id,
		uint64_t	size )

nodiscard

Bind a page-cached paged object to the byte-stream reader.

Parameters

[out]	st	Stream binding to populate (zero-initialised by caller).
[in]	vm	Initialised cache whose loader serves `object_id`.
[in]	object_id	A paged object id registered with `vm's` source.
[in]	size	Object length in bytes (> 0).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Bound; ra8_vmem_stream_read may be used.
k_ra8_err_null_ptr	st or vm was NULL.
k_ra8_err_invalid_size	size was 0, or vm's frame size was 0.

Precondition: vm was populated by ra8_vmem_init and its loader serves object_id.; st out-lives every ra8_vmem_stream_read call that uses it.

Postcondition: On success st->frame_bytes == vm->cfg.frame_bytes and st->size == size.; On any non-ok return st is left unbound.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 33 of file ra8_vmem_stream.c.

References ra8_vmem_t::cfg, ra8_vmem_cfg_t::frame_bytes, ra8_vmem_stream_t::frame_bytes, k_ra8_err_invalid_size, k_ra8_ok, ra8_vmem_stream_t::object_id, RA8_CHECK_NULL_PTR, s_tag, ra8_vmem_stream_t::size, and ra8_vmem_stream_t::vm.

Referenced by internal_cache_bind(), and mem_run_vmem().

◆ ra8_vmem_stream_read()

size_t ra8_vmem_stream_read	(	void *	ctx,
		uint64_t	offset,
		void *	buf,
		size_t	len )

Read len bytes at absolute offset through the page cache.

Pages the covering frames through the SLRU cache one at a time, copying each in-frame slice into buf, and clamps the request to the object end. A read fully past the end returns 0; a partial read (a cache/loader failure mid-span) returns the bytes copied so far, which a consumer like ra8_epub_open_streamed() treats as end-of-file.

Parameters

[in]	ctx	The ra8_vmem_stream_t binding (as a void cookie).
[in]	offset	Absolute byte offset within the object.
[out]	buf	Destination buffer (len writable bytes).
[in]	len	Bytes requested.

Returns: Bytes actually copied (0 at/after EOF or on the first failing frame).

Return values

len	The full request was satisfied (every covering frame paged in).
0	offset is at/after the object end, or the first frame failed.
<len	A frame failed mid-span; the bytes copied before the failure.

Precondition: ctx is a bound ra8_vmem_stream_t; buf is writable for len bytes.; The bound cache and its source out-live this call.

Postcondition: At most one cache frame is pinned at any instant during the copy.; No state outside buf and the cache's LRU order is modified.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 51 of file ra8_vmem_stream.c.

References ra8_vmem_stream_t::frame_bytes, k_ra8_ok, memcpy(), ra8_vmem_stream_t::object_id, ra8_vmem_get(), ra8_vmem_put(), ra8_vmem_stream_t::size, and ra8_vmem_stream_t::vm.

Referenced by internal_stream_open(), and mem_stream_window().

Data Structures

Functions

Detailed Description

Function Documentation

◆ ra8_vmem_stream_init()

◆ ra8_vmem_stream_read()