Read a page-cached object as a seekable byte stream – impl (#147/#151). More...

#include "ra8_vmem_stream.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_vmem.h"

Include dependency graph for ra8_vmem_stream.c:

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.

Variables
static const char *const	s_tag = "ra8_vmem_stream"
	Module log tag.

Detailed Description

Read a page-cached object as a seekable byte stream – impl (#147/#151).

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

Serves an arbitrary (offset, len) span by walking the covering cache frames one at a time: page in the frame that holds cur (ra8_vmem_get), copy the in-frame slice, release the pin (ra8_vmem_put), and advance. At most one frame is pinned at any instant, so the resident set is the caller's fixed ra8_vmem pool plus O(1) – never the object size.

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

Definition in file ra8_vmem_stream.c.

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().

Variable Documentation

◆ s_tag

const char* const s_tag = "ra8_vmem_stream"

static

Module log tag.

Definition at line 30 of file ra8_vmem_stream.c.