Bounded raw-descriptor trace composition for reader_vmem. More...

#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <sys/types.h>
#include <unistd.h>
#include "reader_vmem_internal.h"

Include dependency graph for reader_vmem_host.c:

Macros
#define	_POSIX_C_SOURCE (200809L)
#define	O_CLOEXEC (0)
	No-op close-on-exec fallback for hosts lacking the flag.
#define	O_DIRECTORY (0)
	No-op directory-open fallback for hosts lacking the flag.
#define	O_NOFOLLOW (0)
	No-op no-follow fallback for hosts lacking the flag.

Enumerations
enum	host_limit_t : uint32_t { k_host_temp_attempts = 128U , k_host_decimal_digits = 20U , k_host_decimal_base = 10U , k_host_create_mode = 0666U }
	Host formatting, retry, and creation bounds. More...

Functions
void	priv_rv_diag (const char *text)
	Write one best-effort diagnostic fragment to standard error.
static RA8_INTERNAL size_t	internal_decimal (uint64_t value, char out[k_host_decimal_digits+1U])
	Encode one unsigned value into a caller's fixed buffer.
void	priv_rv_diag_u64 (uint64_t value)
	Write one unsigned decimal diagnostic without stdio.
static RA8_INTERNAL bool	internal_pwrite_exact (int fd, uint64_t offset, const uint8_t *bytes, size_t length)
	Write an exact positioned byte range.
static RA8_INTERNAL bool	internal_split_path (const char *path, char parent[k_rv_host_path_cap], char leaf[k_rv_host_name_cap])
	Split a bounded output path into parent and leaf.
static RA8_INTERNAL bool	internal_temp_name (char out[k_rv_host_name_cap], uint64_t process, uint32_t attempt)
	Build one hidden sibling-temporary leaf.
bool	priv_rv_trace_begin (const char path, rv_trace_t trace)
	Begin one unpublished same-directory trace transaction.
bool	priv_rv_trace_reference (rv_trace_t *trace, uint32_t object_id, uint32_t frame)
	Append one exact object/frame reference to a trace transaction.
bool	priv_rv_trace_commit (rv_trace_t *trace)
	Durably and atomically publish a complete trace.
void	priv_rv_trace_abort (rv_trace_t *trace)
	Close and unlink an unpublished trace.

Detailed Description

Bounded raw-descriptor trace composition for reader_vmem.

Trace bytes are written only to a same-directory sibling temporary. A complete trace is synced and atomically renamed into place; reusable cache and workspace logic has no POSIX dependency.

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

Since: 0.1.0

Definition in file reader_vmem_host.c.

Macro Definition Documentation

◆ _POSIX_C_SOURCE

#define _POSIX_C_SOURCE (200809L)

Definition at line 15 of file reader_vmem_host.c.

◆ O_CLOEXEC

#define O_CLOEXEC (0)

No-op close-on-exec fallback for hosts lacking the flag.

Definition at line 31 of file reader_vmem_host.c.

◆ O_DIRECTORY

#define O_DIRECTORY (0)

No-op directory-open fallback for hosts lacking the flag.

Definition at line 36 of file reader_vmem_host.c.

◆ O_NOFOLLOW

#define O_NOFOLLOW (0)

No-op no-follow fallback for hosts lacking the flag.

Definition at line 41 of file reader_vmem_host.c.

Enumeration Type Documentation

◆ host_limit_t

enum host_limit_t : uint32_t

Host formatting, retry, and creation bounds.

Enumerator
k_host_temp_attempts	Exclusive-create retry bound.
k_host_decimal_digits	Maximum uint64_t digits.
k_host_decimal_base	Decimal conversion radix.
k_host_create_mode	Hosted trace creation mode.

Definition at line 45 of file reader_vmem_host.c.

Function Documentation

◆ internal_decimal()

RA8_INTERNAL size_t internal_decimal	(	uint64_t	value,
		char	out[k_host_decimal_digits+1U] )

static

Encode one unsigned value into a caller's fixed buffer.

Builds digits in reverse locally, then emits a forward NUL-terminated spelling.

Parameters

[in]	value	Unsigned integer to encode in base ten.
[out]	out	Buffer with capacity for every uint64_t digit plus NUL.

Returns: Number of decimal digits, excluding NUL.

Return values

digits A value from one through k_host_decimal_digits.

Precondition: out is non-null and has its declared fixed capacity.; k_host_decimal_digits covers every uint64_t value.

Postcondition: out contains the exact NUL-terminated decimal spelling.; No filesystem or global state changes.

Note: Pure apart from caller output and thread-safe.

Since: 0.1.0

Definition at line 85 of file reader_vmem_host.c.

References k_host_decimal_base, k_host_decimal_digits, and RA8_INTERNAL.

Referenced by internal_temp_name(), priv_rv_diag_u64(), and priv_rv_trace_reference().

◆ internal_pwrite_exact()

RA8_INTERNAL bool internal_pwrite_exact	(	int	fd,
		uint64_t	offset,
		const uint8_t *	bytes,
		size_t	length )

static

Write an exact positioned byte range.

Retries interrupted calls, handles short writes, and rejects offset overflow.

Parameters

[in]	fd	Open private trace descriptor.
[in]	offset	Absolute starting byte offset.
[in]	bytes	Source spanning `length` bytes.
[in]	length	Exact byte count to append positionally.

Returns: Whether every requested byte was written.

Return values

true	Complete range reached the host page cache.
false	Offset overflow or unrecoverable/zero write occurred.

Precondition: bytes spans length readable bytes.; fd remains open for the duration of the call.

Postcondition: Descriptor stream position is unchanged.; Failure may leave only a strict prefix in the unpublished temporary.

Note: Not thread-safe for overlapping ranges.

Since: 0.1.0

Definition at line 125 of file reader_vmem_host.c.

◆ internal_split_path()

RA8_INTERNAL bool internal_split_path	(	const char *	path,
		char	parent[k_rv_host_path_cap],
		char	leaf[k_rv_host_name_cap] )

static

Split a bounded output path into parent and leaf.

Rejects truncation, an empty leaf, and dot traversal components.

Parameters

[in]	path	Requested final trace path.
[out]	parent	Receives the existing parent path.
[out]	leaf	Receives the final filename component.

Returns: Whether both complete components fit and are usable.

Return values

true	Both outputs are NUL-terminated.
false	Path is empty, overlong, or ends in an unusable leaf.

Precondition: All pointers are non-null and outputs have their declared capacities.; path is NUL-terminated.

Postcondition: Success outputs reconstruct path.; Failure touches no filesystem object.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 164 of file reader_vmem_host.c.

References k_rv_host_name_cap, k_rv_host_path_cap, memcpy(), RA8_INTERNAL, strcmp(), and strlen().

Referenced by priv_rv_trace_begin().

◆ internal_temp_name()

RA8_INTERNAL bool internal_temp_name	(	char	out[k_rv_host_name_cap],
		uint64_t	process,
		uint32_t	attempt )

static

Build one hidden sibling-temporary leaf.

Combines fixed prefix, process identifier, and retry index without allocation.

Parameters

[out]	out	Temporary-leaf buffer.
[in]	process	Process identifier.
[in]	attempt	Exclusive-create retry index.

Returns: Whether the complete slash-free name fit.

Return values

true	`out` contains one NUL-terminated hidden leaf.
false	Fixed capacity was insufficient.

Precondition: out has k_rv_host_name_cap writable bytes.; Numeric values are finite and decimal helper bounds hold.

Postcondition: Success builds a name determined only by the arguments.; No filesystem object is touched.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 213 of file reader_vmem_host.c.

References internal_decimal(), k_host_decimal_digits, k_rv_host_name_cap, memcpy(), and s_prefix.

Referenced by priv_rv_trace_begin().

◆ priv_rv_diag()

void priv_rv_diag ( const char * text )

Write one best-effort diagnostic fragment to standard error.

Retries interrupted and short raw-descriptor writes without stdio.

Parameters

[in] text NUL-terminated fragment; null is ignored.

Precondition: text is null or NUL-terminated.; Standard error may accept or reject output.

Postcondition: The complete non-null fragment was attempted.; No cache, trace, or filesystem state changed.

Note: Fragments can interleave with another process.

Since: 0.1.0

Definition at line 52 of file reader_vmem_host.c.

References strlen().

Referenced by internal_execute(), internal_prepare(), internal_report(), internal_report_rate(), internal_report_workspace(), internal_touch(), internal_usage(), priv_rv_diag_u64(), ra8_log_emit_error(), and ra8_log_emit_error_val().

◆ priv_rv_diag_u64()

void priv_rv_diag_u64 ( uint64_t value )

Write one unsigned decimal diagnostic without stdio.

Converts through a fixed local buffer before one bounded fragment write.

Parameters

[in] value Unsigned value to render in base ten.

Precondition: The fixed digit buffer covers every uint64_t value.; Standard error may accept or reject output.

Postcondition: The complete decimal spelling was attempted.; No cache, trace, or filesystem state changed.

Note: Fragments can interleave with another process.

Since: 0.1.0

Definition at line 100 of file reader_vmem_host.c.

References internal_decimal(), k_host_decimal_digits, and priv_rv_diag().

Referenced by internal_report(), internal_report_rate(), internal_report_workspace(), internal_touch(), internal_usage(), and ra8_log_emit_error_val().

◆ priv_rv_trace_abort()

void priv_rv_trace_abort ( rv_trace_t * trace )

Close and unlink an unpublished trace.

Idempotently releases every partially acquired transaction resource.

Parameters

[in,out] trace Trace state returned by the begin operation.

Precondition: trace is non-null and may be partially initialized.; No further append or commit uses the same state concurrently.

Postcondition: Every owned descriptor is closed.; Any owned private leaf is removed; the final trace is unchanged.

Note: Not thread-safe through one trace state.

Since: 0.1.0

Definition at line 312 of file reader_vmem_host.c.

References rv_trace_t::directory_fd, rv_trace_t::temp_exists, rv_trace_t::temp_name, and rv_trace_t::trace_fd.

Referenced by internal_execute(), priv_rv_trace_begin(), and priv_rv_trace_commit().

◆ priv_rv_trace_begin()

bool priv_rv_trace_begin	(	const char *	path,
		rv_trace_t *	trace )

nodiscard

Begin one unpublished same-directory trace transaction.

Definition at line 232 of file reader_vmem_host.c.

References rv_trace_t::directory_fd, rv_trace_t::final_name, internal_split_path(), internal_temp_name(), k_host_create_mode, k_host_temp_attempts, k_rv_host_path_cap, O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW, priv_rv_trace_abort(), rv_trace_t::temp_exists, rv_trace_t::temp_name, and rv_trace_t::trace_fd.

Referenced by internal_execute().

◆ priv_rv_trace_commit()

bool priv_rv_trace_commit ( rv_trace_t * trace )

nodiscard

Durably and atomically publish a complete trace.

Definition at line 287 of file reader_vmem_host.c.

References rv_trace_t::directory_fd, rv_trace_t::final_name, rv_trace_t::io_failed, priv_rv_trace_abort(), renameat(), rv_trace_t::temp_exists, rv_trace_t::temp_name, and rv_trace_t::trace_fd.

Referenced by internal_execute().

◆ priv_rv_trace_reference()

bool priv_rv_trace_reference	(	rv_trace_t *	trace,
		uint32_t	object_id,
		uint32_t	frame )

nodiscard

Append one exact object/frame reference to a trace transaction.

Definition at line 266 of file reader_vmem_host.c.

References internal_decimal(), internal_pwrite_exact(), rv_trace_t::io_failed, k_host_decimal_digits, memcpy(), rv_trace_t::offset, and rv_trace_t::trace_fd.

Referenced by internal_touch().

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ _POSIX_C_SOURCE

◆ O_CLOEXEC

◆ O_DIRECTORY

◆ O_NOFOLLOW

Enumeration Type Documentation

◆ host_limit_t

Function Documentation

◆ internal_decimal()

◆ internal_pwrite_exact()

◆ internal_split_path()

◆ internal_temp_name()

◆ priv_rv_diag()

◆ priv_rv_diag_u64()

◆ priv_rv_trace_abort()

◆ priv_rv_trace_begin()

◆ priv_rv_trace_commit()

◆ priv_rv_trace_reference()