Struct SwmrFileWriter 

pub struct SwmrFileWriter { /* private fields */ }

SWMR writer for streaming frame-based data to an HDF5 file.

Usage:

use rust_hdf5::swmr::SwmrFileWriter;

let mut writer = SwmrFileWriter::create("stream.h5").unwrap();
let ds = writer.create_streaming_dataset::<f32>("frames", &[256, 256]).unwrap();
writer.start_swmr().unwrap();

// Write frames
let frame_data = vec![0.0f32; 256 * 256];
let raw: Vec<u8> = frame_data.iter()
    .flat_map(|v| v.to_le_bytes())
    .collect();
writer.append_frame(ds, &raw).unwrap();
writer.flush().unwrap();

writer.close().unwrap();

Implementations

impl SwmrFileWriter

pub fn create<P: AsRef<Path>>(path: P) -> Result<Self>

Create a new HDF5 file for SWMR streaming using the env-var-derived locking policy.

pub fn create_with_locking<P: AsRef<Path>>( path: P, locking: FileLocking, ) -> Result<Self>

Create a new HDF5 file for SWMR streaming with an explicit locking policy. The writer holds an exclusive lock until Self::start_swmr is called, at which point the lock is downgraded to shared so concurrent SWMR readers can attach.

pub fn open_append<P: AsRef<Path>>(path: P) -> Result<Self>

Reopen a cleanly-closed HDF5 file to resume SWMR streaming.

Existing datasets are reconstructed; locate them with dataset_index, call start_swmr to re-enter SWMR mode, then continue with append_frame. Appending to a multi-frame-chunk dataset (chunk[0] > 1) after reopen is rejected — its final partial band was zero-padded at the original close. Recovering a crashed (never cleanly closed) file is not supported.

pub fn open_append_with_locking<P: AsRef<Path>>( path: P, locking: FileLocking, ) -> Result<Self>

Reopen a cleanly-closed HDF5 file to resume SWMR streaming with an explicit locking policy. See Self::open_append.

pub fn dataset_index(&self, name: &str) -> Option<usize>

Return the index of a dataset by name, or None if absent.

Mainly used after open_append to recover the index of a reconstructed dataset for append_frame.

pub fn create_streaming_dataset<T: H5Type>( &mut self, name: &str, frame_dims: &[u64], ) -> Result<usize>

Create a streaming dataset.

The dataset will have shape [0, frame_dims...] initially, with chunk dimensions [1, frame_dims...] and unlimited first dimension.

Returns the dataset index for use with append_frame.

pub fn create_streaming_dataset_compressed<T: H5Type>( &mut self, name: &str, frame_dims: &[u64], pipeline: FilterPipeline, ) -> Result<usize>

Create a streaming dataset whose frames are compressed.

Like create_streaming_dataset but each appended frame is run through pipeline (e.g. FilterPipeline::deflate(4)). SWMR appends and in-place header updates work the same as for uncompressed streaming datasets.

pub fn create_streaming_dataset_tiled<T: H5Type>( &mut self, name: &str, frame_dims: &[u64], frame_chunk: &[u64], ) -> Result<usize>

Create a streaming dataset whose frames are split into fixed-size chunk tiles.

frame_dims is the per-frame shape (e.g. [1024, 1024]); frame_chunk is the tile shape within a frame (e.g. [256, 256]), of the same rank. The on-disk chunk shape becomes [1, frame_chunk...], so each frame is stored as product(frame_dims / frame_chunk) chunks instead of one. This mirrors area-detector tiling controls such as NDFileHDF5’s nRowChunks / nColChunks: it changes only the partial-read granularity and compression unit, not the stored data. append_frame accepts a whole frame and splits it into tiles automatically.

pub fn create_streaming_dataset_tiled_compressed<T: H5Type>( &mut self, name: &str, frame_dims: &[u64], frame_chunk: &[u64], pipeline: FilterPipeline, ) -> Result<usize>

Create a compressed streaming dataset whose frames are split into fixed-size chunk tiles. See create_streaming_dataset_tiled for the meaning of frame_chunk; each tile is the compression unit.

pub fn create_streaming_dataset_chunked<T: H5Type>( &mut self, name: &str, frame_dims: &[u64], chunk: &[u64], ) -> Result<usize>

Create a streaming dataset with full control over the chunk shape, including the frame axis.

chunk is the complete per-chunk shape, of rank frame_dims.len() + 1: chunk[0] frames per chunk (the NDFileHDF5 nFramesChunks control) and chunk[1..] the per-frame tile shape (nRowChunks / nColChunks). When chunk[0] > 1, append_frame buffers whole frames until a chunk band fills; the final partial band is written (zero-padded) at close, and the dataset’s logical frame count always equals the exact number of frames appended.

pub fn create_streaming_dataset_chunked_compressed<T: H5Type>( &mut self, name: &str, frame_dims: &[u64], chunk: &[u64], pipeline: FilterPipeline, ) -> Result<usize>

Compressed variant of create_streaming_dataset_chunked; each chunk is filtered independently through pipeline.

pub fn create_hard_link( &mut self, parent_group_path: &str, link_name: &str, target_path: &str, ) -> Result<()>

Create a hard link: an additional name for a dataset or group that already exists in the file.

No data is copied — the link and its target share one object header, exactly as h5py / libhdf5 hard links do. This is the NeXus-style way to expose a streaming dataset at an aliased path.

• parent_group_path — full path of the group that will hold the link ("/" for the root group).
• link_name — leaf name of the new link within that group.
• target_path — full path of an existing dataset or group.

Visibility relative to SWMR mode

A link created before start_swmr is committed by start_swmr and is visible to SWMR readers for the whole streaming window. A link created after start_swmr is committed only by close; it does not appear to readers that attach during the live SWMR window. Create layout links before start_swmr when readers must resolve them while streaming.

pub fn create_group( &mut self, parent_group_path: &str, name: &str, ) -> Result<()>

Create a group in the file hierarchy.

• parent_group_path — full path of the parent group ("/" for the root group).
• name — leaf name of the new group.

A nested NeXus layout is built one level at a time, parent first:

writer.create_group("/", "entry").unwrap();
writer.create_group("/entry", "data").unwrap();

Like create_hard_link, a group created before start_swmr is visible to SWMR readers for the whole streaming window; one created after is committed only by close.

pub fn set_group_attr_string( &mut self, group_path: &str, name: &str, value: &str, ) -> Result<()>

Set a string attribute on a group, or on the root group when group_path is "/".

This is the NeXus way to tag a group with its class — for example set_group_attr_string("/entry", "NX_class", "NXentry"). An existing attribute of the same name is replaced.

The same SWMR visibility rule as create_group applies: set before start_swmr for the attribute to be visible to readers during streaming.

pub fn set_group_attr_numeric<T: H5Type>( &mut self, group_path: &str, name: &str, value: &T, ) -> Result<()>

Set a numeric scalar attribute on a group, or on the root group when group_path is "/". An existing attribute of the same name is replaced. See set_group_attr_string for the SWMR visibility rule.

pub fn write_dataset<T: H5Type>( &mut self, name: &str, dims: &[u64], data: &[T], ) -> Result<usize>

Create a fixed-shape (non-streaming) dataset and write all its data in one call. Returns the dataset index.

This is for the NeXus metadata that surrounds the image stream — coordinate axes, detector geometry, and (with dims = &[]) scalar values such as /entry/instrument/detector/distance. Unlike a streaming dataset, it is written once and not appended to.

pub fn write_string_dataset( &mut self, name: &str, strings: &[&str], ) -> Result<usize>

Create a variable-length string dataset (one element per string). Returns the dataset index. Useful for NeXus metadata such as /entry/start_time or per-frame timestamp arrays.

pub fn set_dataset_attr_string( &mut self, ds_index: usize, name: &str, value: &str, ) -> Result<()>

Set a string attribute on a dataset, addressed by its index. The NeXus way to record units, long_name, signal, etc. An existing attribute of the same name is replaced.

pub fn set_dataset_attr_numeric<T: H5Type>( &mut self, ds_index: usize, name: &str, value: &T, ) -> Result<()>

Set a numeric scalar attribute on a dataset, addressed by its index. An existing attribute of the same name is replaced.

pub fn set_dataset_fill_value<T: H5Type>( &mut self, ds_index: usize, value: &T, ) -> Result<()>

Set the fill value of a streaming dataset, addressed by its index.

Call this before the first append_frame: it determines the value of chunk regions that are never written (a partial final band, or unwritten tiles).

pub fn assign_dataset_to_group( &mut self, group_path: &str, ds_index: usize, ) -> Result<()>

Place an existing dataset inside a group.

By default a dataset created through this writer lives at the root level; this moves its link record into group_path (which must already exist). The group must be created before start_swmr for the placement to be visible to readers during streaming.

pub fn start_swmr(&mut self) -> Result<()>

Signal the start of SWMR mode.

pub fn append_frame(&mut self, ds_index: usize, data: &[u8]) -> Result<()>

Append a frame of raw data to a streaming dataset.

The data size must match one frame (product of frame_dims * element_size).

pub fn flush(&mut self) -> Result<()>

Flush all dataset index structures to disk with SWMR ordering.

pub fn close(self) -> Result<()>

Close and finalize the file.