feature, add SWMR (Single-Writer/Multiple-Reader) support

[steven-varga]

Summary

Add high-level C++ wrappers for HDF5 SWMR (Single-Writer/Multiple-Reader) mode. Linux-only in this release.

Background

SWMR allows one writer process to append/modify data while multiple readers access concurrently. It is critical for streaming and real-time append scenarios.

Scope

• Platforms: Linux x86_64 / aarch64 only. macOS and Windows compile-gated out; tracked under a future issue.
• HDF5 floor: >= 1.12.3, gated via feature macro (H5F_ACC_SWMR_WRITE presence) per the ROS3 v2 FAPL pattern.
• Filesystems: Local POSIX (ext4, xfs, btrfs, tmpfs, f2fs) supported. NFS/SMB/overlayfs/Lustre detected at open and warned about; not refused.

HDF5 APIs to wrap

• File open flags: H5F_ACC_SWMR_WRITE, H5F_ACC_SWMR_READ
• File transition: H5Fstart_swmr_write
• Dataset visibility: H5Dflush, H5Drefresh
• FAPL prerequisite: H5Pset_libver_bounds(LATEST, LATEST) — already wrapped as h5::latest_version

Proposed h5cpp API

namespace h5 {

// File-level: SWMR-from-creation (type-level requires latest_version FAPL)
template<class... Args>
fd_t create(std::string path, swmr_write_t, Args&&... args);

template<class... Args>
fd_t open(std::string path, swmr_read_t, Args&&... args);

template<class... Args>
fd_t open(std::string path, swmr_write_t, Args&&... args);

// File-level: transition an existing non-SWMR file
void start_swmr_write(const fd_t& fd);

// Dataset-level: explicit sync points
void flush(const ds_t& ds);     // writer
void refresh(const ds_t& ds);   // reader

} // namespace h5

Composition with existing append pipeline

auto fd = h5::create("stream.h5", h5::swmr_write, h5::latest_version);
auto ds = h5::create<float>(fd, "stream",
    h5::current_dims{0},
    h5::max_dims{H5S_UNLIMITED},
    h5::chunk{4096});

auto pt = h5::create_packet_table(ds, /* ... */);
h5::append(pt, sample);
h5::flush(ds);   // visible to readers after this point

Reader side

auto fd = h5::open("stream.h5", h5::swmr_read);
auto ds = h5::open(fd, "stream");

while (running) {
    h5::refresh(ds);
    auto tail = h5::read<std::vector<float>>(ds, h5::offset{cursor}, h5::count{n});
    // ... process ...
}

Architectural constraints (enforced at type level)

• SWMR writer factory rejects FAPL chains without h5::latest_version.
• SWMR writer factory rejects non-chunked dataset layouts (no contiguous, no compact).
• SWMR APIs are compile-time excluded on non-Linux platforms; h5::flush(ds) is a compile error, not a runtime exception, on macOS/Windows.

Filesystem detection

At open, statfs(2) classifies the filesystem. NFS/SMB/overlayfs/parallel-FS produce a one-line warning on h5::error::iostream; opt-out via H5CPP_SWMR_NO_FS_CHECK=1.

Acceptance Criteria

• h5::create(path, swmr_write, ...) and h5::open(path, swmr_read, ...) factories
• h5::start_swmr_write(fd) transition wrapper
• h5::flush(ds) / h5::refresh(ds) dataset wrappers
• Type-level rejection of non-latest_version FAPL and non-chunked layout for SWMR writer
• CMake gates HDF5 < 1.12.3 with FATAL_ERROR
• CMake excludes SWMR sources on non-Linux platforms
• Multi-process ctest harness: 1 writer + N readers, fork-based, covers basic round-trip, multi-reader fan-out, writer crash, reader-before-first-flush, transition mid-stream
• Filesystem warning emitted for NFS mount in synthetic test
• Documentation: docs/SWMR.md with failure-mode catalog and known limitations

Out of scope (separate issues)

• macOS / Windows / BSD SWMR support
• Reader polling helpers (application policy)
• Parallel HDF5 SWMR (PHDF5)
• NFS / Lustre certification

References

• HDF5 SWMR User Guide: https://support.hdfgroup.org/documentation/hdf5/latest/_s_w_m_r.html
• Architecture report: vargalabs-workspace/tasks/h5cpp-swmr-architecture-report.md