You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# H5CPP — High-Performance [HDF5][hdf5] for Modern C++
11
+
Modern C++ for HDF5
12
+
--------------------
13
+
**H5CPP** is a modern C++ template library for serial and parallel HDF5 I/O. It provides type-safe RAII wrappers, high-level `create` / `read` / `write` / `append` operations, and seamless interoperability with the native HDF5 C API. Chunked and compressed datasets, extendable packet-table streams, hyperslab selection, custom datatypes, and MPI parallel I/O are all supported. HDF5 files written by H5CPP are readable from Python, R, MATLAB, Fortran, Julia, and any other HDF5-capable environment.
14
+
15
+
| Layer | Role |
16
+
|---|---|
17
+
|**H5CPP**| Header-only C++ HDF5 I/O library |
18
+
|[h5cpp-compiler][compiler]| Optional build-time reflection tool for non-POD struct persistence |
| Windows |![NA][NA]|![NA][NA]|![NA][NA]|![NA][NA]|![NA][NA]|![NA][NA]|![NA][NA]|![NA][NA]|![msvc][500]|
18
28
19
-
H5CPP is a modern C++ template library for serial and parallel HDF5 I/O. It provides type-safe RAII wrappers, high-level `create` / `read` / `write` / `append` operations, and seamless interoperability with the native HDF5 C API. Chunked and compressed datasets, extendable packet-table streams, hyperslab selection, custom datatypes, and MPI parallel I/O are all supported. HDF5 files written by H5CPP are readable from Python, R, MATLAB, Fortran, Julia, and any other HDF5-capable environment.
20
-
21
29
## Quick Start
22
30
23
31
```cpp
24
32
#include<h5cpp/all>
25
33
#include<vector>
26
34
35
+
namespacesn::sensor {
36
+
struct [[h5::doc("Time-series sensor reading with variable-length fields"),
-**FAPL-scoped worker pool** — `h5::create(..., h5::threads{N} | h5::backpressure{M})` opts the file into parallel filter compression; all chunked datasets opened on that file (and pt_t built from them) inherit the pool. The pool only parallelizes gzip/zstd and never touches the HDF5 C-API, so it is throughput-neutral versus the classic single-threaded build.
95
-
-**`-DH5CPP_MULTITHREAD` build mode** — a compile-time option that serializes every h5cpp→HDF5 C-API call behind one process-global recursive mutex, taken once at the outermost boundary via a thread-local recursion depth (mirroring HDF5's own `--enable-threadsafe` design: a lock, not a dedicated thread). This makes concurrent writers into one file safe even on a Threadsafety-OFF HDF5, and compiles to a zero-cost no-op in a classic build. Verified green on HDF5 1.12.3 and 2.1.1 (62/62 ctest, 40/40 concurrent-writer stress, TSan-clean under Clang 20).
96
-
-**HDF5 1.12.2 ceiling** — tested and verified; `H5Dvlen_reclaim` / reference API compatibility
97
-
-**Windows MSVC** in the CI matrix
98
-
-**ASan + UBSan + TSan** clean on Clang 20
105
+
## v1.14.0
106
+
107
+
v1.14.0 closes the v1.12.x line — a cycle organized around eliminating the performance and concurrency objections that push teams from HDF5 toward ad-hoc formats.
108
+
109
+
-**STL non-contiguous and sequence containers** — `std::valarray`, `std::list`, `std::deque`, `std::set`, `std::multiset`, `std::unordered_set`, `std::unordered_multiset` all route through the unified Walter Brown trait-based dispatch. `std::complex<T>` and `std::float16_t` (C++23 half-precision) datasets added.
110
+
-**Rank-7 arrays** — up to seven-dimensional arrays supported, matching the HDF5 C library limit.
111
+
-**Expanded attribute coverage** — all scalar, string, and compound attribute types reachable through the same `h5::awrite` / `h5::aread` surface.
112
+
-**SSSE3 rank-1 write fast path** — chunked 1-D writes use a bump-pointer arena, prefetch, nontemporal stores, and SIMD shuffle/unshuffle for element sizes 2, 4, and 8 bytes. No API changes; existing code picks it up automatically on x86 targets. Non-x86 targets use the scalar path unchanged.
113
+
-**In-place filter pipeline** — shuffle, Fletcher-32, scale-offset, and nbit run without heap allocation, cutting per-chunk overhead on write-heavy workloads.
114
+
-**Transparent concurrent compression** — the filter pipeline (gzip/zstd) runs across a per-file worker pool internally; the write API stays synchronous and single-threaded. Activate at file open with `h5::create(..., h5::threads{N} | h5::backpressure{M})`; no THREAD_SAFE HDF5 build required.
115
+
-**Parallel decompression** — rank-1 chunked reads decompress across the same per-file pool, scaling with available threads.
116
+
-**`h5::view<T>` streaming ranges** — C++20 range view over chunked datasets; `for (auto chunk : h5::view<std::vector<float>>(ds))` iterates multi-GB datasets one chunk at a time without materialising the full dataset in memory. Any container satisfying Walter Brown's detection idiom (`data()`, `value_type`, `size()`) works as the element type, so Abseil, Folly, EASTL, and Boost.Container all participate without registration.
117
+
-**Gorilla XOR filter***(experimental)* — delta-of-delta XOR codec for `float32`/`float64` time-series (Facebook Gorilla algorithm). Interoperability with h5py and the HDF5 C library for Gorilla-compressed datasets is not yet tested.
118
+
-**Scatter/gather dispatch** — `H5CPP_REGISTER_SCATTER` lets any third-party container opt into `h5::read` / `h5::write` without modifying the library.
119
+
-**Compiler-assisted reflection** — `h5cpp-compiler`, a Clang LibTooling pre-build tool, emits HDF5 compound descriptors and scatter/gather helpers for any non-POD struct without intrusive macros. Struct members are annotated with C++26-style attributes; the tool walks the AST at build time and generates the descriptors. C++26 static reflection is on the roadmap as the macro-free successor.
120
+
-**SWMR** — `swmr_write_t` / `swmr_read_t` tags enable live readers to observe an active writer without closing the file. Requires HDF5 ≥ 1.12.3; `H5CPP_HAS_SWMR` is set automatically by CMake.
121
+
-**HDF5 2.x compatibility** — `H5Dread_chunk2` buffer-sizing fix; existing code runs correctly on HDF5 2.x without source changes.
122
+
-**Doxygen API reference** — full reference live at [vargalabs.github.io/h5cpp][docs], with I/O API, topics, and cookbook navigation axes.
123
+
-**28 CMake cookbook examples** — basics through MPI, S3, sparse matrices, half-float, and custom pipelines; enable with `-DH5CPP_BUILD_EXAMPLES=ON`.
124
+
-**Public CDash dashboard** — CI results and sanitiser status at <https://my.cdash.org/index.php?project=h5cpp>; community submissions welcomed.
125
+
-**Coverage > 95%**, TSan-clean on Clang 20, ASan and UBSan clean across the full matrix.
0 commit comments