Merge branch 'staging' into release

Author: steven-varga

.github/workflows/ci.yml

@@ -67,7 +67,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -131,7 +131,7 @@ jobs:
           set -euxo pipefail
 
           brew update
-          brew install cmake ninja hdf5
+          brew install --quiet cmake ninja hdf5
 
           HDF5_PREFIX="$(brew --prefix hdf5)"
 
@@ -195,7 +195,7 @@ jobs:
       - name: Restore HDF5 1.10.10 cache
         if: runner.os == 'Windows'
         id: cache-hdf5
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@v5
         with:
           path: ${{ runner.temp }}\hdf5-${{ env.HDF5_VERSION }}-install
           key: hdf5-${{ runner.os }}-${{ matrix.compiler }}-${{ env.HDF5_VERSION }}-${{ env.HDF5_CACHE_VERSION }}
@@ -241,7 +241,7 @@ jobs:
 
       - name: Save HDF5 1.10.10 cache
         if: runner.os == 'Windows' && steps.cache-hdf5.outputs.cache-hit != 'true'
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@v5
         with:
           path: ${{ runner.temp }}\hdf5-${{ env.HDF5_VERSION }}-install
           key: ${{ steps.cache-hdf5.outputs.cache-primary-key }}
@@ -282,6 +282,7 @@ jobs:
             -DCMAKE_CXX_STANDARD=23
             -DCMAKE_BUILD_TYPE=Release
             -DH5CPP_BUILD_TESTS=ON
+            -DH5CPP_BUILD_EXAMPLES=ON
           )
 
           if [[ -n "${HDF5_ROOT:-}" ]]; then
@@ -339,7 +340,7 @@ jobs:
 
       - name: Upload Status Artifact
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: status-${{ matrix.os }}-${{ matrix.compiler }}
           path: badge-status/status-${{ matrix.os }}-${{ matrix.compiler }}.json
@@ -359,7 +360,7 @@ jobs:
           sudo apt-get install -y jq curl
 
       - name: Download all status artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           path: badge-status
           pattern: status-*
@@ -430,7 +431,7 @@ jobs:
 
       - name: Upload badges artifact
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: ${{ github.ref_name == 'staging' && 'badges-staging' || 'badges' }}
           path: ${{ github.ref_name == 'staging' && 'badges-staging' || 'badges' }}
@@ -456,7 +457,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -488,7 +489,8 @@ jobs:
             -DCMAKE_CXX_COMPILER=g++-14 \
             -DCMAKE_C_FLAGS="--coverage -O0 -g" \
             -DCMAKE_CXX_FLAGS="--coverage -O0 -g" \
-            -DH5CPP_BUILD_TESTS=ON
+            -DH5CPP_BUILD_TESTS=ON \
+            -DH5CPP_BUILD_EXAMPLES=ON
 
       - name: Build
         shell: bash
@@ -530,7 +532,7 @@ jobs:
           lcov --gcov-tool /usr/bin/gcov-14 --list coverage.info
 
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           files: ./coverage.info
           disable_search: true

.github/workflows/docs.yml

@@ -13,10 +13,10 @@ jobs:
 
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.x'
 

CMakeLists.txt

@@ -42,6 +42,7 @@ endif()
 # ─── Options ──────────────────────────────────────────────────────────────────────
 option(H5CPP_BUILD_EXAMPLES "Build examples" OFF)
 option(H5CPP_BUILD_TESTS    "Build tests"    OFF)
+option(H5CPP_BUILD_BENCH    "Build benches"  OFF)
 option(H5CPP_USE_LIBDEFLATE "Use libdeflate for H5CPP deflate/gzip filters when available" ON)
 option(H5CPP_REQUIRE_LIBDEFLATE "Fail configuration if H5CPP_USE_LIBDEFLATE is ON and libdeflate is not found" OFF)
 option(H5CPP_INSTALL_LIBDEFLATE "Install the resolved libdeflate header and library with H5CPP" OFF)
@@ -103,6 +104,8 @@ if(MPI_FOUND AND HDF5_IS_PARALLEL)
 endif()
 
 # ─── Include Directories & Libraries ──────────────────────────────────────────────
+find_package(ZLIB REQUIRED)
+
 list(APPEND H5CPP_INCLUDE_DIRS
     ${CMAKE_CURRENT_SOURCE_DIR}
     ${HDF5_INCLUDE_DIRS}
@@ -198,6 +201,10 @@ if(H5CPP_BUILD_TESTS AND EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/test/CMakeLists.txt)
     add_subdirectory(test)
 endif()
 
+if(H5CPP_BUILD_BENCH AND EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/bench/CMakeLists.txt)
+    add_subdirectory(bench)
+endif()
+
 # ─── Install Rules ────────────────────────────────────────────────────────────────
 if(WIN32)
     set(INSTALL_DIR_CMAKE    "${CMAKE_INSTALL_PREFIX}/share/h5cpp/cmake")

README.md

@@ -1,5 +1,5 @@
 [![CI](https://github.com/vargalabs/h5cpp/actions/workflows/ci.yml/badge.svg)](https://github.com/vargalabs/h5cpp/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/vargalabs/h5cpp/branch/main/graph/badge.svg)](https://app.codecov.io/gh/vargalabs/h5cpp/tree/main)
+[![codecov](https://codecov.io/gh/vargalabs/h5cpp/branch/release/graph/badge.svg)](https://app.codecov.io/gh/vargalabs/h5cpp/tree/release)
 [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20123216.svg)](https://doi.org/10.5281/zenodo.20123216)
 [![GitHub release](https://img.shields.io/github/v/release/vargalabs/h5cpp.svg)](https://github.com/vargalabs/h5cpp/releases)

bench/CMakeLists.txt

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: MIT
+# This file is part of H5CPP.
+# Copyright (c) 2025-2026 Varga Labs, Toronto, ON, Canada.
+
+find_package(ZLIB REQUIRED)
+
+set(INCLUDE_DIRS
+    ${CMAKE_CURRENT_SOURCE_DIR}/..
+    ${HDF5_C_INCLUDE_DIRS}
+)
+
+set(LIBS
+    ${HDF5_LIBRARIES}
+    ZLIB::ZLIB
+    libh5cpp-libdeflate
+)
+
+# ─── nanobench harness (vendored single header) ─────────────────────────────────────
+set(HARNESS_SOURCES
+    ${CMAKE_CURRENT_SOURCE_DIR}/harness/nanobench.h
+)
+
+# ─── Common bench compile settings ──────────────────────────────────────────────────
+function(add_bench file_name)
+    set(options)
+    set(one_value_args)
+    set(multi_value_args LIBRARIES)
+    cmake_parse_arguments(ARG "${options}" "${one_value_args}" "${multi_value_args}" ${ARGN})
+
+    add_executable(bench-${file_name} workloads/${file_name}.cpp ${HARNESS_SOURCES})
+    target_include_directories(bench-${file_name} PRIVATE ${INCLUDE_DIRS})
+    target_link_libraries(bench-${file_name} PRIVATE ${LIBS} ${ARG_LIBRARIES})
+    # Intentionally not adding -Wall -Wextra: h5cpp core headers have
+    # pre-existing warnings that would pollute bench output. The bench
+    # code itself is simple and checked with the same rigor as tests.
+    set_target_properties(bench-${file_name} PROPERTIES
+        CXX_STANDARD 17
+        CXX_STANDARD_REQUIRED ON
+        CXX_EXTENSIONS OFF
+    )
+endfunction()
+
+# ─── Workload benches ───────────────────────────────────────────────────────────────
+add_bench(sequential)
+add_bench(filesystem_ceiling)
+add_bench(containers)
+add_bench(chunked_filtered)
+add_bench(high_throughput)
+add_bench(small_object)
+
+# ─── Aggregate target ───────────────────────────────────────────────────────────────
+add_custom_target(h5cpp-bench DEPENDS
+    bench-sequential
+    bench-filesystem_ceiling
+    bench-containers
+    bench-chunked_filtered
+    bench-high_throughput
+    bench-small_object
+)

bench/README.md

@@ -0,0 +1,46 @@
+# h5cpp Bench Suite
+
+Reproducible performance benchmarks for h5cpp I/O throughput claims.
+
+## Quick Start
+
+```bash
+cmake -B build -DH5CPP_BUILD_BENCH=ON -DCMAKE_BUILD_TYPE=Release
+cmake --build build --target h5cpp-bench
+./build/bench/bench-sequential
+```
+
+## Design
+
+See `tasks/h5cpp-performance-evaluation-framework-design.md` in the workspace repo for the full architecture report.
+
+## Workloads
+
+| Bench | What It Measures |
+|-------|------------------|
+| `bench-sequential` | 1D `vector<double>` write/read throughput at 1K–10M elements |
+| `bench-filesystem_ceiling` | Raw `fwrite`/`fread` bandwidth ceiling on `/dev/shm` |
+| `bench-containers` | h5cpp high-level vs raw HDF5 C API overhead |
+| `bench-chunked_filtered` | Chunked write with gzip, zstd, lz4, shuffle+gzip |
+| `bench-high_throughput` | Standard path (direct chunk comparison deferred) |
+| `bench-small_object` | Latency for single values, 4 KB vectors, structs |
+
+## Output
+
+Each bench prints a markdown table to stdout. To suppress the table and emit JSON:
+
+```bash
+./build/bench/bench-sequential > /dev/null 2> results.json
+```
+
+*(JSON export is a v2 enhancement; currently stdout only.)*
+
+## Methodology
+
+- Files are created on `/dev/shm` (tmpfs) to eliminate disk variance.
+- Synthetic data uses a fixed seed (`42`) for reproducible compression ratios.
+- Each benchmark case runs enough iterations for nanobench to reach statistical stability.
+
+## CI
+
+The `bench` job runs on `ubuntu-24.04 / gcc-14` in Release mode. It is **advisory only** — never blocks merge.

bench/fixtures/synthetic.hpp

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025-2026 Varga Labs, Toronto, ON, Canada.
+#pragma once
+
+#include <vector>
+#include <random>
+#include <cstddef>
+
+namespace bench::fixture {
+
+// Deterministic pseudo-random data generator for reproducible benchmarks.
+// Same seed => same bytes => same compression ratios.
+class Synthetic {
+public:
+    explicit Synthetic(std::uint64_t seed = 42) : rng_(seed) {}
+
+    std::vector<double> doubles(std::size_t n) {
+        std::vector<double> out(n);
+        std::uniform_real_distribution<double> dist(-1.0, 1.0);
+        for (auto& v : out) v = dist(rng_);
+        return out;
+    }
+
+    std::vector<std::uint8_t> bytes(std::size_t n) {
+        std::vector<std::uint8_t> out(n);
+        std::uniform_int_distribution<int> dist(0, 255);
+        for (auto& v : out) v = static_cast<std::uint8_t>(dist(rng_));
+        return out;
+    }
+
+private:
+    std::mt19937_64 rng_;
+};
+
+} // namespace bench::fixture

bench/harness/config.hpp

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025-2026 Varga Labs, Toronto, ON, Canada.
+#pragma once
+
+#include <vector>
+#include <cstdlib>
+#include <cstddef>
+
+namespace bench {
+
+inline bool is_ci() {
+    const char* env = std::getenv("H5CPP_BENCH_CI");
+    return env && env[0] == '1';
+}
+
+// Returns tiny sizes for CI (smoke test only) or 1GB/10GB for real benchmarking.
+inline std::vector<std::size_t> payload_sizes() {
+    if (is_ci()) {
+        return {1'000};  // 8 KB — enough to exercise the code path
+    }
+    return {
+        125'000'000,    // 1 GB
+        1'250'000'000,  // 10 GB
+    };
+}
+
+// Single default payload size for benches that don't sweep sizes.
+inline std::size_t default_payload_size() {
+    return is_ci() ? 1'000 : 125'000'000;  // 8 KB vs 1 GB
+}
+
+} // namespace bench