Bounded byte-source and text-sink seams for cache_bench. More...

#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for cache_bench_io.h:

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

Data Structures
struct	cb_source_t
	Immutable injected byte source with a snapshotted length. More...
struct	cb_sink_t
	Injected output sink. More...
struct	cb_scratch_t
	Injected bounded random-access scratch transaction. More...

Typedefs
typedef cb_io_status_t(*	cb_source_read_fn) (void ctx, uint64_t offset, uint8_t dst, size_t capacity, size_t *out_read)
	Read-at callback; zero bytes is EOF, short reads are permitted.
typedef cb_io_status_t(*	cb_sink_write_fn) (void ctx, const uint8_t data, size_t length, size_t *out_written)
	Write callback; short writes are permitted.
typedef cb_io_status_t(*	cb_scratch_io_fn) (void ctx, uint64_t offset, void data, size_t length)
	Random-access scratch-file callback.

Enumerations
enum	cb_io_status_t : uint8_t { k_cb_io_ok = 0U , k_cb_io_fault = 1U , k_cb_io_capacity = 2U , k_cb_io_mutated = 3U }
	Status returned by tool-local injected I/O callbacks. More...

Functions
cb_io_status_t	cb_sink_write_all (cb_sink_t sink, const void data, size_t length)
	Write every byte, retrying bounded short writes.
cb_io_status_t	cb_sink_vformat (cb_sink_t sink, const char format, va_list args)
	Format one bounded record and publish it atomically to the sink seam.
cb_io_status_t	cb_sink_format (cb_sink_t sink, const char format,...)
	Format one bounded record and publish it atomically to the sink seam.

Detailed Description

Bounded byte-source and text-sink seams for cache_bench.

Defines the ownership-neutral callbacks used by replay, reporting, scratch-backed containers, and host composition.

[Ring 7 / Tooling] {World: NS}

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

Since: 0.1.0

Definition in file cache_bench_io.h.

Typedef Documentation

◆ cb_scratch_io_fn

typedef cb_io_status_t(* cb_scratch_io_fn) (void *ctx, uint64_t offset, void *data, size_t length)

Random-access scratch-file callback.

Definition at line 51 of file cache_bench_io.h.

◆ cb_sink_write_fn

typedef cb_io_status_t(* cb_sink_write_fn) (void *ctx, const uint8_t *data, size_t length, size_t *out_written)

Write callback; short writes are permitted.

Definition at line 39 of file cache_bench_io.h.

◆ cb_source_read_fn

typedef cb_io_status_t( * cb_source_read_fn) (void *ctx, uint64_t offset, uint8_t *dst, size_t capacity, size_t *out_read)

Read-at callback; zero bytes is EOF, short reads are permitted.

Definition at line 28 of file cache_bench_io.h.

Enumeration Type Documentation

◆ cb_io_status_t

enum cb_io_status_t : uint8_t

Status returned by tool-local injected I/O callbacks.

Enumerator
k_cb_io_ok	Operation completed.
k_cb_io_fault	Backing device or sink failed.
k_cb_io_capacity	Caller-owned storage was too small.
k_cb_io_mutated	A replay source changed between passes.

Definition at line 20 of file cache_bench_io.h.

Function Documentation

◆ cb_sink_format()

cb_io_status_t cb_sink_format	(	cb_sink_t *	sink,
		const char *	format,
			... )

Format one bounded record and publish it atomically to the sink seam.

Formats into fixed automatic storage, rejects truncation, then delegates complete publication to cb_sink_write_all.

Parameters

[in,out]	sink	Destination binding.
[in]	format	printf-compatible format string.
[in]	args	Format arguments.

Returns: k_cb_io_ok, k_cb_io_capacity, or a sink failure.

Return values

k_cb_io_ok	The complete formatted record was published.
k_cb_io_capacity	Formatting exceeded the fixed record capacity.
k_cb_io_fault	A binding, formatting, or sink operation failed.

Precondition: sink and format are non-NULL.; args matches the conversions in format.

Postcondition: On formatting failure, no bytes are offered to sink.; On success, exactly one complete formatted record is published.

Note: The function acquires no storage and retains no va_list state.

Since: 0.1.0

Definition at line 58 of file cache_bench_io.c.

References cb_sink_vformat().

Referenced by cb_sweep_block(), internal_print_verdict(), internal_report_summary(), internal_report_trace_header(), internal_report_trace_row(), internal_run_capacity(), internal_summary(), main(), priv_print_crossover(), priv_print_hot_table(), priv_print_row(), and priv_print_seq_table().

◆ cb_sink_vformat()

cb_io_status_t cb_sink_vformat	(	cb_sink_t *	sink,
		const char *	format,
		va_list	args )

Format one bounded record and publish it atomically to the sink seam.

Formats into fixed automatic storage, rejects truncation, then delegates complete publication to cb_sink_write_all.

Parameters

[in,out]	sink	Destination binding.
[in]	format	printf-compatible format string.
[in]	args	Format arguments.

Returns: k_cb_io_ok, k_cb_io_capacity, or a sink failure.

Return values

k_cb_io_ok	The complete formatted record was published.
k_cb_io_capacity	Formatting exceeded the fixed record capacity.
k_cb_io_fault	A binding, formatting, or sink operation failed.

Precondition: sink and format are non-NULL.; args matches the conversions in format.

Postcondition: On formatting failure, no bytes are offered to sink.; On success, exactly one complete formatted record is published.

Note: The function acquires no storage and retains no va_list state.

Since: 0.1.0

Definition at line 45 of file cache_bench_io.c.

References cb_sink_write_all(), k_cb_format_capacity, k_cb_io_capacity, and k_cb_io_fault.

Referenced by cb_sink_format().

◆ cb_sink_write_all()

cb_io_status_t cb_sink_write_all	(	cb_sink_t *	sink,
		const void *	data,
		size_t	length )

Write every byte, retrying bounded short writes.

Repeatedly invokes the injected sink until length bytes complete, rejecting zero progress, over-counts, or the first sink failure.

Parameters

[in,out]	sink	Destination binding.
[in]	data	Bytes to publish.
[in]	length	Byte count.

Returns: k_cb_io_ok on complete publication, otherwise the first failure.

Return values

k_cb_io_ok	Every byte was accepted.
k_cb_io_fault	The binding failed or the sink made invalid progress.
k_cb_io_capacity	The injected sink reported insufficient capacity.

Precondition: sink has a non-NULL write callback.; data is readable for length bytes when length is non-zero.

Postcondition: On success, exactly length bytes were published in order.; On failure, no retry occurs after the first terminal status.

Note: Atomicity beyond an individual callback is provided by the bound sink.

Since: 0.1.0

Definition at line 22 of file cache_bench_io.c.

References cb_sink_t::ctx, k_cb_io_fault, k_cb_io_ok, k_cb_write_limit, and cb_sink_t::write.

Referenced by cb_sink_vformat().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ cb_scratch_io_fn

◆ cb_sink_write_fn

◆ cb_source_read_fn

Enumeration Type Documentation

◆ cb_io_status_t

Function Documentation

◆ cb_sink_format()

◆ cb_sink_vformat()

◆ cb_sink_write_all()