Reporting for the #208 sweep: machine-parseable rows, per-leg summary tables, and the measured knee / crossover verdict. More...

#include <stdio.h>
#include <string.h>
#include "sweep_block_internal.h"

Include dependency graph for sweep_block_report.c:

Data Structures
struct	cbs_knee_t
	The computed crossover of the chunked backend's sequential sweep. More...

Functions
RA8_PRIV int	priv_print_row (cb_sink_t sink, const cbs_row_t r)
	Implementation of priv_print_row() – one key=value line.
static RA8_INTERNAL void	internal_block_label (uint32_t block, char *out, size_t cap)
	Format a block size as a short label ("512B", "64K") into `out`.
static RA8_INTERNAL const cbs_row_t *	internal_find_row (const cbs_row_t rows, uint32_t n, const char be, const char *leg, uint32_t block)
	Find the row for (backend, leg, block), or NULL.
static RA8_INTERNAL double	internal_row_mibs (const cbs_row_t *r)
	Delivered-payload throughput of a row in MiB/s.
RA8_PRIV int	priv_print_seq_table (cb_sink_t sink, const cbs_row_t rows, uint32_t nrows, const char be, const uint32_t blocks, uint32_t nblocks)
	Implementation of priv_print_seq_table() – Ch 23.2 miss-cost split.
RA8_PRIV int	priv_print_hot_table (cb_sink_t sink, const cbs_row_t rows, uint32_t nrows, const char be, const uint32_t blocks, uint32_t nblocks)
	Implementation of priv_print_hot_table() – pure hit-path table.
static RA8_INTERNAL bool	internal_find_knee (const cbs_row_t rows, uint32_t nrows, const uint32_t blocks, uint32_t nblocks, cbs_knee_t *out)
	Locate the rbkc-z9 sequential throughput peak and knee.
static RA8_INTERNAL int	internal_print_verdict (cb_sink_t sink, const cbs_knee_t knee, const char knee_label, const char default_label, double knee_pct)
	Publish the knee/default relationship as one bounded paragraph.
RA8_PRIV int	priv_print_crossover (cb_sink_t sink, const cbs_row_t rows, uint32_t nrows, const uint32_t *blocks, uint32_t nblocks)
	Implementation of priv_print_crossover() – knee verdict prose.

Variables
static const double	s_cbs_pct_f = 100.0
	100.0 as a double, for percentage maths.
static const double	s_cbs_mib_f = 1048576.0
	Bytes per MiB as a double, for throughput maths.
static const double	s_cbs_ns_per_s_f = 1000000000.0
	Nanoseconds per second as a double, for throughput maths.
static const double	s_cbs_ns_per_us_f = 1000.0
	Nanoseconds per microsecond as a double, for latency maths.

Detailed Description

Reporting for the #208 sweep: machine-parseable rows, per-leg summary tables, and the measured knee / crossover verdict.

Consumes the finished cbs_row_t array the sweep core produced. The machine-parseable sweep-block key=value ... rows are printed as each leg finishes; the human summary (one sequential and one hot-path markdown table per backend, then the crossover paragraph naming the measured knee against the 64 KiB .rabook chunk default from #204) is printed once the sweep completes. Pure readers: nothing here mutates row data.

[Ring 7 / Tooling] {World: NS}

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

Since: 0.1.0

Definition in file sweep_block_report.c.

Function Documentation

◆ internal_block_label()

RA8_INTERNAL void internal_block_label	(	uint32_t	block,
		char *	out,
		size_t	cap )

static

Format a block size as a short label ("512B", "64K") into out.

Writes a KiB label with snprintf for sizes at or above one KiB and a byte label below that, truncating safely to cap, so table rows stay narrow and aligned.

Parameters

[in]	block	Block size in bytes to label.
[out]	out	Destination buffer (NUL-terminated by snprintf).
[in]	cap	Capacity of `out` in bytes.

Precondition: out has cap writable bytes when cap > 0.; Called on the single benchmark thread.

Postcondition: On cap > 0, out holds a NUL-terminated label.; No state other than out is modified.

Note: Not thread-safe: writes the caller's buffer (no shared state).

Since: 0.1.0

Definition at line 89 of file sweep_block_report.c.

References k_cbs_kib.

Referenced by priv_print_crossover(), priv_print_hot_table(), and priv_print_seq_table().

◆ internal_find_knee()

RA8_INTERNAL bool internal_find_knee	(	const cbs_row_t *	rows,
		uint32_t	nrows,
		const uint32_t *	blocks,
		uint32_t	nblocks,
		cbs_knee_t *	out )

static

Locate the rbkc-z9 sequential throughput peak and knee.

Scans the chunked backend's sequential rows for the peak MiB/s, then walks the sizes ascending and takes the first whose throughput reaches k_cbs_knee_pct percent of that peak – the smallest block where per-request overhead has stopped dominating.

Parameters

[in]	rows	All finished rows.
[in]	nrows	Number of rows.
[in]	blocks	The swept sizes, ascending.
[in]	nblocks	Number of swept sizes.
[out]	out	Receives the peak + knee.

Returns: bool true when rbkc-z9 sequential rows existed, false otherwise.

Return values

true	`out` is fully populated.
false	No usable rows; `out` is zeroed.

Precondition: blocks is sorted ascending (the first size over the bar wins).; out is writable.

Postcondition: On true, out->knee_mibs >= k_cbs_knee_pct% * out->peak_mibs.; No row data is modified.

Note: Thread-safe over quiescent rows (pure read).

Since: 0.1.0

Definition at line 278 of file sweep_block_report.c.

References internal_find_row(), internal_row_mibs(), k_cbs_knee_pct, cbs_knee_t::knee_block, cbs_knee_t::knee_mibs, cbs_knee_t::peak_block, cbs_knee_t::peak_mibs, and s_cbs_pct_f.

Referenced by priv_print_crossover().

◆ internal_find_row()

RA8_INTERNAL const cbs_row_t * internal_find_row	(	const cbs_row_t *	rows,
		uint32_t	n,
		const char *	be,
		const char *	leg,
		uint32_t	block )

static

Find the row for (backend, leg, block), or NULL.

Definition at line 103 of file sweep_block_report.c.

References strcmp().

Referenced by internal_find_knee(), priv_print_hot_table(), and priv_print_seq_table().

◆ internal_print_verdict()

RA8_INTERNAL int internal_print_verdict	(	cb_sink_t *	sink,
		const cbs_knee_t *	knee,
		const char *	knee_label,
		const char *	default_label,
		double	knee_pct )

static

Publish the knee/default relationship as one bounded paragraph.

Selects the equal, below-default, or above-default explanation and writes it through the injected report sink.

Parameters

[in,out]	sink	Report destination.
[in]	knee	Measured peak and knee result.
[in]	knee_label	Human-readable measured knee size.
[in]	default_label	Human-readable configured default size.
[in]	knee_pct	Knee throughput as a percentage of peak.

Returns: Zero after complete publication, otherwise one.

Return values

0	The selected paragraph was accepted by `sink`.
1	The sink rejected the paragraph.

Precondition: All pointer parameters are non-NULL.; knee contains a successful internal_find_knee result.

Postcondition: Exactly one relationship paragraph is attempted.; knee and label bytes are not modified.

Note: The paragraph is advisory; hardware confirmation remains required.

Since: 0.1.0

Definition at line 334 of file sweep_block_report.c.

References cb_sink_format(), k_cb_io_ok, k_cbs_default_chunk, and cbs_knee_t::knee_block.

Referenced by priv_print_crossover().

◆ internal_row_mibs()

RA8_INTERNAL double internal_row_mibs ( const cbs_row_t * r )

static

Delivered-payload throughput of a row in MiB/s.

Computes reads * k_cbs_req_bytes delivered bytes over the row's wall time, clamping a zero wall time to 1 ns so the division is always defined. Used by the summary tables and the knee search.

Parameters

[in] r Finished row (NULL or zero-reads yields 0.0).

Returns: double Throughput in MiB/s, or 0.0 when r is empty.

Return values

0.0	`r` is NULL or recorded no reads.
other	The delivered-payload throughput in MiB/s.

Precondition: r is NULL, or a finished row with final counters.; Called on the single benchmark thread.

Postcondition: r is not modified (pure read).; No global state is touched.

Note: Thread-safe over a quiescent row (pure read).

Since: 0.1.0

Definition at line 143 of file sweep_block_report.c.

References k_cbs_req_bytes, cbs_row_t::reads, s_cbs_mib_f, s_cbs_ns_per_s_f, and cbs_row_t::wall_ns.

Referenced by internal_find_knee(), and priv_print_seq_table().

◆ priv_print_crossover()

RA8_PRIV int priv_print_crossover	(	cb_sink_t *	sink,
		const cbs_row_t *	rows,
		uint32_t	nrows,
		const uint32_t *	blocks,
		uint32_t	nblocks )

Implementation of priv_print_crossover() – knee verdict prose.

Name the measured crossover and print the chunk-size recommendation.

Definition at line 370 of file sweep_block_report.c.

References cb_sink_format(), internal_block_label(), internal_find_knee(), internal_print_verdict(), k_cb_io_ok, k_cbs_default_chunk, k_cbs_knee_pct, cbs_knee_t::knee_block, cbs_knee_t::knee_mibs, cbs_knee_t::peak_block, cbs_knee_t::peak_mibs, and s_cbs_pct_f.

Referenced by internal_summary().

◆ priv_print_hot_table()

RA8_PRIV int priv_print_hot_table	(	cb_sink_t *	sink,
		const cbs_row_t *	rows,
		uint32_t	nrows,
		const char *	be,
		const uint32_t *	blocks,
		uint32_t	nblocks )

Implementation of priv_print_hot_table() – pure hit-path table.

Print one backend's same-block re-read summary table (leg b).

Definition at line 204 of file sweep_block_report.c.

References cb_sink_format(), cbs_row_t::hits, internal_block_label(), internal_find_row(), k_cb_io_ok, cbs_row_t::misses, cbs_row_t::reads, and cbs_row_t::wall_ns.

Referenced by internal_summary().

◆ priv_print_row()

RA8_PRIV int priv_print_row	(	cb_sink_t *	sink,
		const cbs_row_t *	r )

Implementation of priv_print_row() – one key=value line.

Print one machine-parseable result row (sweep-block key=value ...).

Definition at line 37 of file sweep_block_report.c.

References cbs_row_t::backend, cbs_row_t::backing_bytes, cbs_row_t::be_bytes, cbs_row_t::be_calls, cbs_row_t::block_bytes, cb_sink_format(), cbs_row_t::evictions, cbs_row_t::frames, cbs_row_t::hits, k_cb_io_ok, k_cbs_ns_per_us, k_cbs_req_bytes, cbs_row_t::leg, cbs_row_t::misses, cbs_row_t::reads, s_cbs_mib_f, s_cbs_ns_per_s_f, cbs_row_t::src_bytes, and cbs_row_t::wall_ns.

Referenced by internal_run_block().

◆ priv_print_seq_table()

RA8_PRIV int priv_print_seq_table	(	cb_sink_t *	sink,
		const cbs_row_t *	rows,
		uint32_t	nrows,
		const char *	be,
		const uint32_t *	blocks,
		uint32_t	nblocks )

Implementation of priv_print_seq_table() – Ch 23.2 miss-cost split.

Print one backend's sequential-scan summary table (leg a).

Definition at line 155 of file sweep_block_report.c.

References cbs_row_t::backing_bytes, cbs_row_t::be_calls, cb_sink_format(), cbs_row_t::frames, internal_block_label(), internal_find_row(), internal_row_mibs(), k_cb_io_ok, cbs_row_t::misses, cbs_row_t::reads, s_cbs_mib_f, s_cbs_ns_per_us_f, cbs_row_t::src_bytes, and cbs_row_t::wall_ns.

Referenced by internal_summary().

Variable Documentation

◆ s_cbs_mib_f

const double s_cbs_mib_f = 1048576.0

static

Bytes per MiB as a double, for throughput maths.

Definition at line 29 of file sweep_block_report.c.

Referenced by internal_row_mibs(), priv_print_row(), and priv_print_seq_table().

◆ s_cbs_ns_per_s_f

const double s_cbs_ns_per_s_f = 1000000000.0

static

Nanoseconds per second as a double, for throughput maths.

Definition at line 31 of file sweep_block_report.c.

Referenced by internal_row_mibs(), and priv_print_row().

◆ s_cbs_ns_per_us_f

const double s_cbs_ns_per_us_f = 1000.0

static

Nanoseconds per microsecond as a double, for latency maths.

Definition at line 33 of file sweep_block_report.c.

Referenced by priv_print_seq_table().

◆ s_cbs_pct_f

const double s_cbs_pct_f = 100.0

static

100.0 as a double, for percentage maths.

Definition at line 27 of file sweep_block_report.c.

Referenced by internal_find_knee(), and priv_print_crossover().

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ internal_block_label()

◆ internal_find_knee()

◆ internal_find_row()

◆ internal_print_verdict()

◆ internal_row_mibs()

◆ priv_print_crossover()

◆ priv_print_hot_table()

◆ priv_print_row()

◆ priv_print_seq_table()

Variable Documentation

◆ s_cbs_mib_f

◆ s_cbs_ns_per_s_f

◆ s_cbs_ns_per_us_f

◆ s_cbs_pct_f