Struct File 

pub struct File { /* private fields */ }

An open HDF5 file.

A File is an owned, cheaply cloneable handle to an open file: cloning it (or deriving a Dataset/Group from it) shares one underlying open file rather than re-reading it. Object handles returned by dataset, group, and root are owned — they keep the file open for as long as they live and carry no borrow of the File, so they can be stored in a struct, cached, and moved across threads.

Implementations

impl File

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Open an HDF5 file from a filesystem path.

Reads the file into memory once. To follow a file that a concurrent single writer is appending to (SWMR), use File::open_swmr instead. To read a file larger than memory (e.g. on a 32-bit host) without buffering it, use File::open_streaming.

A file whose superblock marks it as held by a writer is refused with Error::FileMarkedInUse — the check H5Fopen makes of the same byte. That means a live writer or one that exited without closing the file; clear a stale flag with clear_swmr_flag, and follow a live SWMR writer with open_swmr. from_bytes does not check, since its caller already holds the bytes — which is also the way to read a flagged file on a read-only mount, where clearing the flag would need write access.

pub fn open_with_options<P: AsRef<Path>>( path: P, properties: FileAccessProperties, ) -> Result<Self, Error>

Open an HDF5 file from a filesystem path with explicit access properties.

pub fn open_streaming<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Open an HDF5 file for streaming reads, fetching regions on demand from the file instead of buffering it whole.

This lets a host read a file larger than its address space. Metadata and dataset chunks are read through a ReadSeekSource, so peak memory stays close to one chunk plus the metadata being parsed. Attribute reading and v1 symbol-table groups on the resolved path are not yet supported on this backend.

Like open, this refuses a file whose superblock marks it as held by a writer.

pub fn open_streaming_with_options<P: AsRef<Path>>( path: P, properties: FileAccessProperties, ) -> Result<Self, Error>

Open an HDF5 file for streaming reads with explicit access properties.

pub fn open_swmr<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Open an HDF5 file for SWMR (single-writer/multiple-reader) reading.

Like File::open, but retains a live handle to the file so that File::refresh can re-read data appended by a concurrent writer.

This is the open that follows a file marked as held by a SWMR writer, where open refuses one. Only a half-set mark is refused here, with Error::FileMarkedInUse: either bit without the other. Write access alone is what a plain (non-SWMR) writer leaves, and there is no protocol for following a writer that is not publishing consistent prefixes; the SWMR bit alone is a state no writer produces. Both bits is the live SWMR writer this exists to follow, and neither is a quiescent file.

pub fn open_swmr_with_options<P: AsRef<Path>>( path: P, properties: FileAccessProperties, ) -> Result<Self, Error>

Open an HDF5 file for SWMR reading with explicit access properties.

pub fn from_bytes(data: Vec<u8>) -> Result<Self, Error>

Open an HDF5 file from an in-memory byte vector.

pub fn from_bytes_with_options( data: Vec<u8>, properties: FileAccessProperties, ) -> Result<Self, Error>

Open an HDF5 file from an in-memory byte vector with explicit access properties.

pub fn open_rw<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Open an existing HDF5 file for reading and in-place editing.

Unlike open (read-only, buffered), this takes an exclusive OS file lock held for the file’s life and lets owned handles modify the file — immediate Dataset::appends, plus Dataset::write/set_attr, Group::create_dataset/create_group/delete/set_attr, and copy/copy_from staged until commit. The file must use 8-byte offsets and lengths and keep its superblock at its base address (a canonical userblock, as in a MATLAB .mat file, is supported); anything else is refused with Error::EditUnsupported.

The fast immediate Dataset::append additionally requires a latest-format (version-2/3) file with no userblock and an Extensible-Array-indexed dataset; Dataset::append_staged covers the general case.

Two things can turn this open away because another writer holds the file: the exclusive OS lock, reported as Error::FileLocked, and the superblock’s status-flags byte, reported as Error::FileMarkedInUse. The second covers what the first cannot — a SWMR writer takes no lock, and a writer that exited without closing the file leaves the flag behind; recover a stale one with clear_swmr_flag.

Memory

This picks its backing from the file rather than making the caller pick a function (issue #198): a latest-format file with no userblock is edited bounded, holding only the metadata being parsed plus the configured caches plus what an edit is building, so resident memory does not scale with the file; anything else falls back to a whole-file in-memory mirror, which is what makes a pre-v2 or userblock file editable at all. The two backings are the same engine over different storage and offer the same edit surface, differing in one trade: the bounded one applies a large immediate append in whole-chunk batches, each crash-atomic on its own, so a crash mid-call leaves a valid shorter dataset rather than none of the append. Ask a file which it got with edit_backing, and demand one with FileAccessProperties::with_memory_strategy — MemoryStrategy::Mirrored restores the unconditional mirror this entry point used before it learned to dispatch.

pub fn open_rw_with_options<P: AsRef<Path>>( path: P, properties: FileAccessProperties, ) -> Result<Self, Error>

Open an existing file for reading and in-place editing with explicit access properties — see open_rw.

The properties carry the locking policy (the H5Pset_file_locking analogue, FileAccessProperties::with_locking), the memory strategy (FileAccessProperties::with_memory_strategy, which overrides the dispatch described on open_rw), the metadata cache used by the bounded backing, and the file-wide chunk-cache default applied to datasets opened from this file. Because one FileAccessProperties value serves every open, the same configuration can be shared with a read path.

pub fn open_swmr_writer<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Open an existing file for SWMR (single-writer/multiple-reader) appending: take no OS lock (so concurrent readers, and Windows’ mandatory locks, are never blocked) and raise the superblock’s SWMR-write flag so a reader may attach with File::open_swmr, the C library’s H5F_ACC_SWMR_READ, or h5py swmr=True.

Only immediate Dataset::append is permitted, and only over the SWMR subset — an unfiltered, chunk-aligned append, so a concurrent reader only ever observes a consistent prefix; a filtered or non-chunk-aligned append returns Error::SwmrAppendUnsupported. The staged edit surface (write/set_attr/create_*/delete/copy/ commit) returns Error::SwmrStagedUnsupported. close clears the SWMR-write flag; a writer that exits without a clean close leaves it set — recover with clear_swmr_flag. While the flag stands, this open is refused with Error::FileMarkedInUse, which is what keeps a second writer off a file SWMR gives only one (no OS lock is held to do it).

Requires a latest-format (version-3 superblock) file with no userblock and no persisted free-space; other files are refused with Error::SwmrAppendUnsupported. The version-3 requirement is the C library’s: neither library reads the SWMR-write flag back on an older superblock, so raising one there would announce the writer to nobody.

pub fn open_swmr_writer_with_options<P: AsRef<Path>>( path: P, properties: FileAccessProperties, ) -> Result<Self, Error>

Open for SWMR appending with explicit access properties — see open_swmr_writer.

The properties’ chunk cache is the file-wide default for datasets opened from this file. Its locking policy is ignored, which costs the caller nothing: SWMR takes no OS lock by design, which is stronger than any locking a caller could ask for. Its memory strategy is not ignored the same way — this writer always mirrors, so an explicit MemoryStrategy::Bounded is a guarantee it cannot meet and is refused with Error::EditUnsupported; MemoryStrategy::Auto and MemoryStrategy::Mirrored are both satisfied by the mirror.

pub fn open_rw_bounded<P: AsRef<Path>>(path: P) -> Result<Self, Error>

👎Deprecated since 0.28.0:

use File::open_rw, which now edits such a file bounded on its own; for the strict refusal, pass FileAccessProperties::new().with_memory_strategy(MemoryStrategy::Bounded) to File::open_rw_with_options

Open an existing HDF5 file for reading and editing with bounded memory (issue #147): no whole-file mirror is ever built, so peak memory stays at the metadata being parsed plus the configured caches plus a few chunks of append working set — independent of the file size and of the size of each append call.

Deprecated

open_rw now edits such a file bounded on its own, so this is no longer a different capability set — only a different default for a file the bounded engine cannot edit (a pre-v2 superblock, or a userblock). This refuses that file with Error::EditUnsupported; open_rw mirrors it instead. To keep the refusal, say so:

use hdf5_pure::{File, FileAccessProperties, MemoryStrategy};
let file = File::open_rw_with_options(
    "data.h5",
    FileAccessProperties::new().with_memory_strategy(MemoryStrategy::Bounded),
)?;

Behavior

This is the read-write sibling of open_streaming: reads are served by positioned I/O with the same capabilities as the streaming backend, while immediate Dataset::append runs the same crash-atomic engine as open_rw — filtered whole-chunk / unfiltered any-length, durable before it returns, no commit needed. A large append is applied in whole-chunk batches, each crash-atomic, so a crash mid-call leaves a valid shorter dataset. An exclusive OS file lock is held for the file’s life.

The staged edit surface (Dataset::write/set_attr/append_staged, Group::create_dataset/create_group/delete/set_attr, commit/copy/copy_from, and space_accounting) is the same as open_rw’s: both open the same engine, differing only in how it holds the file’s bytes (issue #198). A commit here holds only what it is building, so its resident memory is bounded by the edit rather than by the file — with copy the exception, since copying an object reads the whole of it into memory first.

A file that persists its free space (H5Pset_file_space_strategy(persist = true), non-paged) is supported: its on-disk free-space managers are seeded at open and rewritten into canonical shape when the file is closed — by an explicit close or, best-effort, when the last handle drops (issue #173). Only a true crash (SIGKILL, power loss) skips that rewrite; the appended data is still durable and reopens correctly, the managers merely stay non-canonical until the next clean rewrite. A genuine paged file (H5F_FSPACE_STRATEGY_PAGE with persist = true) is also supported: appends stay page-homogeneous (raw and metadata in separate pages) and the per-page-type managers are rewritten at close. A paged file that does not persist its free space is refused at open — recreate it with persist = true to grow it in place. That refusal is shared with open_rw, which cannot commit such a file either.

Requires a latest-format (v2/v3 superblock) file with 8-byte offsets and lengths and no userblock; other files are refused at open with Error::EditUnsupported.

pub fn open_rw_bounded_with_options<P: AsRef<Path>>( path: P, properties: FileAccessProperties, ) -> Result<Self, Error>

👎Deprecated since 0.28.0:

use File::open_rw_with_options; it honors the same with_memory_strategy, and defaults to falling back to the mirror rather than refusing

Open a file for bounded-memory reading and appending with explicit access properties — see open_rw_bounded, which this is deprecated alongside.

Both configured caches apply to this backend: the metadata cache bounds bytes retained for metadata reads (entries touched by an in-place write are invalidated, so reads never observe stale bytes), and the chunk cache bounds decompressed chunks retained by each Dataset handle. An explicit FileAccessProperties::with_memory_strategy wins over this entry point’s bounded default, in either direction.

pub fn clear_swmr_flag<P: AsRef<Path>>(path: P) -> Result<(), Error>

Clear a stale SWMR-write flag left in path by a writer that exited without a clean close — the h5clear -s equivalent, for recovering a file that both this crate and the reference C library otherwise refuse to open (Error::FileMarkedInUse). A no-op if the flag is already clear.

It takes the exclusive OS lock first, so it cannot clear the flag out from under a live open_rw writer. A live SWMR writer holds no lock, so make sure it is really gone: clearing the flag under one leaves its readers with no record that it is publishing.

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

Create a new, empty HDF5 file at path and open it for reading and writing, so its contents can be built entirely through owned handles (Group::create_dataset/create_group, then commit).

Overwrites any existing file at path. For an all-at-once write, use FileBuilder instead.

pub fn create_with_options<P: AsRef<Path>>( path: P, create: FileCreateProperties, access: FileAccessProperties, ) -> Result<Self, Error>

Create a new, empty HDF5 file with explicit creation and access properties, then open it for reading and writing — see create.

Mirrors H5Fcreate(name, flags, fcpl_id, fapl_id): create carries the creation properties recorded in the new file (userblock, file-space strategy, library-version bounds), and access the properties governing the handle returned (locking policy, chunk cache). Both are values, so a layout defined once can be reused across every file an application writes.

A creation property is validated as the file is written, so an invalid userblock or page size surfaces here rather than when the properties were built. A file created with FileSpaceStrategy::Page can be grown through either editor, by an immediate Dataset::append or a staged commit, provided it also persists its free space (issue #198).

pub fn commit(&self) -> Result<(), Error>

Apply all staged structural edits made through this file’s handles — Dataset::write/set_attr/remove_attr and Group::create_group/delete — as one transaction. Immediate Dataset::appends need no commit.

Requires a read-write file (File::open_rw); a read-only file returns Error::ReadOnly. A commit that relocates objects invalidates outstanding handles — re-fetch any you keep using.

pub fn copy(&self, src: &str, dst: &str) -> Result<(), Error>

Copy the object at src to dst within this file (the in-file H5Ocopy), staged until commit.

Requires a read-write file (File::open_rw); a read-only file returns Error::ReadOnly.

pub fn copy_from( &self, source: &File, src: &str, dst: &str, ) -> Result<(), Error>

Copy the object at src in source — a separate, buffered read-only file — into this file at dst: the cross-file H5Ocopy, staged until commit.

source must be a buffered file (File::open or File::from_bytes, not File::open_streaming) that uses 8-byte offsets and has no userblock; anything else is refused with Error::EditUnsupported. The source subtree is read and validated eagerly, so source need not outlive this call. Requires a read-write destination (File::open_rw); a read-only one returns Error::ReadOnly.

pub fn has_staged_edits(&self) -> bool

Report whether this file has structural edits staged but not yet applied by commit — Dataset::write/set_attr/remove_attr, Dataset::append_staged, Group::create_group/create_dataset/ delete/set_attr/remove_attr, and copy/ copy_from. Immediate Dataset::appends are never staged and do not count. Always false for a read-only file.

pub fn space_accounting(&self) -> Result<SpaceAccounting, Error>

Report this read-write file’s live space usage as a SpaceAccounting — the current logical size, total reusable free bytes, and reusable free regions. It reflects committed state plus immediate in-place appends, not edits still staged for commit.

Requires a read-write file (File::open_rw); a read-only file returns Error::ReadOnly.

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

Commit any staged edits and seal this file. The exclusive OS lock is released once the last handle derived from this file is also dropped.

After close, a write through any surviving Dataset/Group handle or File clone returns Error::FileClosed; reads still work.

pub fn root(&self) -> Group

Returns an owned handle to the root group.

pub fn dataset(&self, path: &str) -> Result<Dataset, Error>

Resolve a path and return an owned Dataset handle.

The dataset uses the file-wide chunk-cache default (configured with FileAccessProperties::with_chunk_cache). To override the cache for this one dataset, use dataset_with_options.

pub fn dataset_with_options( &self, path: &str, properties: DatasetAccessProperties, ) -> Result<Dataset, Error>

Resolve a path and return an owned Dataset handle, applying per-dataset DatasetAccessProperties that override file-wide access defaults.

This is the dataset-open-with-access-property-list path (HDF5’s dapl): the properties’ chunk cache corresponds to H5Pset_chunk_cache and takes precedence, for this dataset only, over the H5Pset_cache-style file-wide default.

pub fn group(&self, path: &str) -> Result<Group, Error>

Resolve a path and return an owned Group handle.

pub fn refresh(&mut self) -> Result<(), Error>

Re-read the file from disk to pick up data appended by a concurrent writer, then re-parse the superblock.

This is the SWMR reader’s refresh primitive. Returns Error::SwmrUnsupported if the file was not opened with File::open_swmr, and Error::HandlesOutstanding if any owned Dataset/Group handle (or a clone of this File) is still alive — drop them before refreshing, then re-fetch them afterward, since they observe the new bytes only when re-derived from the refreshed file.

pub fn as_bytes(&self) -> &[u8]

Returns the raw file bytes for an in-memory file, or an empty slice for a streaming file (which has no whole-file buffer).

pub fn access_properties(&self) -> FileAccessProperties

Return the access properties used when opening this file.

pub fn access_options(&self) -> FileAccessProperties

👎Deprecated since 0.26.0:

renamed to access_properties

Former name of access_properties.

pub fn edit_backing(&self) -> Option<EditBacking>

Which backend this file’s read-write session resolved to: EditBacking::Bounded when it reads through a handle, or EditBacking::Mirrored when it holds a whole-file image.

This is how a caller who opened with MemoryStrategy::Auto finds out whether the fallback was taken, and so whether memory scales with the file. A file with no editing session — a read-only open, a streaming open — reports None.

The answer is an EditBacking rather than the MemoryStrategy that was asked for, because Auto is a preference between the two backends and not an outcome either can report; .into() converts back when a later reopen should be pinned to what this one got.

pub fn superblock(&self) -> &Superblock

Returns a reference to the parsed superblock.

pub fn file_space_strategy(&self) -> Option<FileSpaceStrategy>

The file-space management strategy this file records in its superblock extension, or None if it records none.

pub fn file_space_info(&self) -> Option<&FileSpaceInfo>

The full FileSpaceInfo recorded in this file’s superblock extension, if present and readable.

pub fn persisted_free_space(&self) -> Vec<(u64, u64)>

The free regions a file persists on disk in its free-space managers, as (address, length) pairs sorted by address.

pub fn file_size(&self) -> u64

The size of the underlying file in bytes (the HDF5 H5Fget_filesize).

pub fn libver_bound(&self) -> LibVer

The minimum library version required to read this file, derived from its superblock version (the low bound of HDF5’s H5Fget_libver_bounds).

Trait Implementations

impl Clone for File

fn clone(&self) -> File

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for File

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.