Resettable, allocation-free access streams for cache_bench. More...

#include <stdint.h>
#include "cache_bench.h"
#include "cache_bench_io.h"

Include dependency graph for trace.h:

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

Data Structures
struct	cb_trace
	Named resettable trace; captured bytes remain owned by the caller. More...
struct	cb_trace_cursor_t
	Caller-owned state for one independent trace pass. More...

Typedefs
typedef struct cb_trace	cb_trace_t
	Named resettable trace; captured bytes remain owned by the caller.

Enumerations
enum	cb_trace_limit_t : uint16_t { k_cb_synthetic_trace_count = 8U , k_cb_trace_name_capacity = 64U , k_cb_trace_line_capacity = 128U , k_cb_trace_read_capacity = 256U }
	Number of built-in deterministic workloads. More...
enum	cb_trace_kind_t : uint8_t { k_cb_trace_seq = 0U , k_cb_trace_random , k_cb_trace_reread , k_cb_trace_jumps , k_cb_trace_scroll , k_cb_trace_scan , k_cb_trace_huge , k_cb_trace_mixed , k_cb_trace_captured }
	Workload implementation selected by a trace descriptor. More...

Functions
void	cb_traces_synthetic (cb_trace_t out[k_cb_synthetic_trace_count])
	Populate the fixed built-in corpus without acquiring storage.
cb_io_status_t	cb_trace_bind (const cb_source_t source, const char name, size_t name_length, cb_trace_t *out)
	Validate and bind one captured decimal <object> <page> source.
cb_io_status_t	cb_trace_cursor_open (const cb_trace_t trace, cb_trace_cursor_t cursor)
	Reset a cursor for an independent pass over a trace.
cb_io_status_t	cb_trace_cursor_next (cb_trace_cursor_t cursor, cb_key_t key, bool *done)
	Emit the next key.
cb_io_status_t	cb_trace_cursor_finish (const cb_trace_cursor_t *cursor)
	Validate a captured pass against its bound count and fingerprint.

Detailed Description

Resettable, allocation-free access streams for cache_bench.

Defines immutable trace descriptors and caller-owned cursors for deterministic synthetic or injected captured workloads.

[Ring 7 / Tooling] {World: NS}

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

Since: 0.1.0

Definition in file trace.h.

Typedef Documentation

◆ cb_trace_t

typedef struct cb_trace cb_trace_t

Named resettable trace; captured bytes remain owned by the caller.

Enumeration Type Documentation

◆ cb_trace_kind_t

enum cb_trace_kind_t : uint8_t

Workload implementation selected by a trace descriptor.

Enumerator
k_cb_trace_seq	Sequential page walk.
k_cb_trace_random	Uniform pseudo-random accesses.
k_cb_trace_reread	Hot-set reread workload.
k_cb_trace_jumps	Mostly sequential with jumps.
k_cb_trace_scroll	Repeated scrolling window.
k_cb_trace_scan	Hot-set plus streaming scan.
k_cb_trace_huge	Oversized hot-set and scan.
k_cb_trace_mixed	Alternating access phases.
k_cb_trace_captured	Caller-injected captured accesses.

Definition at line 29 of file trace.h.

◆ cb_trace_limit_t

enum cb_trace_limit_t : uint16_t

Number of built-in deterministic workloads.

Enumerator
k_cb_synthetic_trace_count	Fixed corpus size.
k_cb_trace_name_capacity	Captured trace display-name bound.
k_cb_trace_line_capacity	Historical line-parser bound.
k_cb_trace_read_capacity	Bounded source read-ahead.

Definition at line 21 of file trace.h.

Function Documentation

◆ cb_trace_bind()

cb_io_status_t cb_trace_bind	(	const cb_source_t *	source,
		const char *	name,
		size_t	name_length,
		cb_trace_t *	out )

Validate and bind one captured decimal <object> <page> source.

Copies the bounded display name, validates a complete pass through the injected source, and snapshots its count plus fingerprint.

Parameters

[in]	source	Borrowed immutable byte source.
[in]	name	Display name bytes (need not be NUL-terminated).
[in]	name_length	Display-name byte count.
[out]	out	Bound trace on success; zeroed on failure.

Returns: I/O, capacity, or success status.

Return values

k_cb_io_ok	`out` contains a validated captured trace.
k_cb_io_capacity	The display name exceeds fixed storage.
k_cb_io_fault	A binding, parser, or source contract failed.
k_cb_io_mutated	The source changed during validation.

Precondition: source has a non-NULL read callback and stable size snapshot.; name and out are non-NULL.

Postcondition: On success, out borrows source and owns its copied name only.; On failure, out is all-zero.

Note: Caller must keep the source context alive through every replay.

Since: 0.1.0

Definition at line 473 of file trace.c.

References cb_trace_cursor_next(), cb_trace_cursor_open(), cb_trace::fingerprint, cb_trace_cursor_t::fingerprint, cb_trace_cursor_t::index, k_cb_io_capacity, k_cb_io_fault, k_cb_io_ok, k_cb_trace_captured, k_cb_trace_name_capacity, memcpy(), cb_trace::n, cb_trace::name, cb_trace::name_storage, and cb_source_t::read.

Referenced by internal_load_argv_traces().

◆ cb_trace_cursor_finish()

cb_io_status_t cb_trace_cursor_finish ( const cb_trace_cursor_t * cursor )

Validate a captured pass against its bound count and fingerprint.

Compares emitted count and accumulated fingerprint with the values snapshotted by cb_trace_bind; synthetic passes require count only.

Parameters

[in] cursor Finished trace cursor.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	Count and, for captured traces, fingerprint match.
k_cb_io_fault	A binding or count check failed.
k_cb_io_mutated	Captured content changed between passes.

Precondition: cursor and cursor->trace are non-NULL.; Iteration reached clean completion before this call.

Postcondition: Cursor and trace state are not modified.; A captured mismatch is distinguishable from an ordinary fault.

Note: This closes logical validation only; it owns no host descriptor.

Since: 0.1.0

Definition at line 459 of file trace.c.

References cb_trace::fingerprint, cb_trace_cursor_t::fingerprint, cb_trace_cursor_t::index, k_cb_io_fault, k_cb_io_mutated, k_cb_io_ok, k_cb_trace_captured, cb_trace::kind, cb_trace::n, and cb_trace_cursor_t::trace.

Referenced by internal_replay_stream().

◆ cb_trace_cursor_next()

cb_io_status_t cb_trace_cursor_next	(	cb_trace_cursor_t *	cursor,
		cb_key_t *	key,
		bool *	done )

Emit the next key.

Dispatches to the captured parser or selected deterministic generator, then advances count and fingerprint for emitted keys.

Parameters

[in,out]	cursor	Open cursor.
[out]	key	Next key when done is false.
[out]	done	True at a clean end.

Returns: Source/parser status.

Return values

k_cb_io_ok	A key or clean end was produced.
k_cb_io_fault	A cursor, generator, parser, or source contract failed.
k_cb_io_mutated	The injected source reported mutation.

Precondition: All pointers are non-NULL and cursor is open.; key and done point to writable storage.

Postcondition: When done is false, cursor count advances and key is initialized.; Once the declared count is reached, done is true.

Note: Call cb_trace_cursor_finish after termination to validate stability.

Since: 0.1.0

Definition at line 438 of file trace.c.

References cb_trace_cursor_t::fingerprint, cb_trace_cursor_t::index, internal_trace_captured_next(), internal_trace_hash(), internal_trace_synthetic_next(), k_cb_io_fault, k_cb_io_ok, k_cb_trace_captured, cb_trace::kind, cb_trace::n, and cb_trace_cursor_t::trace.

Referenced by cb_trace_bind(), and internal_replay_stream().

◆ cb_trace_cursor_open()

cb_io_status_t cb_trace_cursor_open	(	const cb_trace_t *	trace,
		cb_trace_cursor_t *	cursor )

Reset a cursor for an independent pass over a trace.

Clears cursor state, binds trace, and selects the deterministic seed required by its workload kind.

Parameters

[in]	trace	Immutable trace descriptor.
[out]	cursor	Cursor to initialize.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	The cursor is ready for its first key.
k_cb_io_fault	An argument or trace kind is invalid.

Precondition: trace and cursor are non-NULL.; trace was initialized by a published trace binder.

Postcondition: On success, cursor index and fingerprint are at their initial values.; trace is not modified and remains borrowed.

Note: Distinct cursors may replay the same immutable trace independently.

Since: 0.1.0

Definition at line 418 of file trace.c.

References cb_trace::fingerprint, k_cb_hash_offset, k_cb_io_fault, k_cb_io_ok, k_cb_trace_captured, k_cb_trace_jumps, k_cb_trace_mixed, k_cb_trace_random, k_cb_trace_reread, k_rng_seed_mixed_a, k_rng_seed_mixed_b, k_rng_seed_random, k_rng_seed_reread, k_rng_seed_toc, cb_trace::kind, cb_source_t::read, cb_trace_cursor_t::rng, and cb_trace::source.

Referenced by cb_trace_bind(), and internal_replay_stream().

◆ cb_traces_synthetic()

void cb_traces_synthetic ( cb_trace_t out[k_cb_synthetic_trace_count] )

Populate the fixed built-in corpus without acquiring storage.

Initializes all names, counts, footprints, and generator kinds in stable report order.

Parameters

[out] out Array of k_cb_synthetic_trace_count descriptors.

Precondition: out is non-NULL and has the declared array capacity.; Static corpus geometry fits the published descriptor fields.

Postcondition: Every output descriptor is initialized and resettable.; No external storage or ownership is acquired.

Note: Descriptor names point to read-only static strings.

Since: 0.1.0

Definition at line 141 of file trace.c.

References k_cb_accesses, k_cb_footprint, k_cb_huge_footprint, k_cb_synthetic_trace_count, and k_cb_tile_span.

Referenced by internal_run_capacity().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ cb_trace_t

Enumeration Type Documentation

◆ cb_trace_kind_t

◆ cb_trace_limit_t

Function Documentation

◆ cb_trace_bind()

◆ cb_trace_cursor_finish()

◆ cb_trace_cursor_next()

◆ cb_trace_cursor_open()

◆ cb_traces_synthetic()