perf(format): back large read buffers with transparent huge pages

A full read of a contiguous dataset is one memcpy from the mapped file,
yet ran at a quarter of h5py's speed on one thread: the fresh output Vec
took a page fault and a kernel page clear for every 4 KiB page written,
16384 per 64 MiB, costing several times the copy (the benchmark spent
6.2 s of 8 s in the kernel, 4.3M minor faults). numpy, so h5py, madvises
MADV_HUGEPAGE on allocations of 4 MiB or more; the typed readers' output,
the raw contiguous read and the chunk assembly buffer now do the same
(Linux only, libc as a Linux-only dependency; no-op otherwise).

New h5py comparison tests cover full and selection reads of contiguous
data for every 1-8-byte integer and float type, both byte orders, ranks
1-4, empty selections, and datasets past the 4 MiB threshold.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

crates/clawhdf5-format/Cargo.toml

@@ -30,6 +30,10 @@ ruzstd = { version = "0.9", optional = true }
 bzip2 = { version = "0.6", optional = true }
 snap = { version = "1", optional = true }
 
+[target.'cfg(target_os = "linux")'.dependencies]
+# madvise(MADV_HUGEPAGE) for large read buffers (see src/bulk_alloc.rs).
+libc = { version = "0.2", default-features = false }
+
 [dev-dependencies]
 half = { workspace = true }
 serde_json = "1"

crates/clawhdf5-format/src/bulk_alloc.rs

@@ -0,0 +1,78 @@
+//! Large output buffers backed by transparent huge pages where the OS offers
+//! them.
+//!
+//! A fresh multi-megabyte `Vec` is mapped lazily by the kernel: the first
+//! write to each 4 KiB page takes a page fault, and the kernel zeroes the page
+//! before handing it over. For a 64 MiB read that is 16384 faults, and they
+//! cost far more than the copy that fills the buffer — single-threaded
+//! contiguous reads ran at about a quarter of h5py's speed because of them.
+//! numpy (so h5py) avoids this by asking for transparent huge pages
+//! (`madvise(MADV_HUGEPAGE)`) on every allocation of 4 MiB or more, which
+//! turns 512 faults into one; this module does the same.
+//!
+//! The advice only changes how the pages are backed, never their contents, so
+//! it is harmless when it cannot be honoured (THP disabled, not Linux, a
+//! region that is part of the heap): the buffer is then exactly what it would
+//! have been without it.
+
+#[cfg(not(feature = "std"))]
+use alloc::vec::Vec;
+
+/// Buffers smaller than this are left alone (numpy uses the same threshold).
+pub(crate) const HUGE_PAGE_THRESHOLD: usize = 4 << 20;
+
+/// Advise the kernel to back `[ptr, ptr + len)` with transparent huge pages,
+/// when `len` is large enough to benefit. Call it before the first write so
+/// the faults happen at huge-page granularity.
+#[inline]
+pub(crate) fn advise_huge_pages(ptr: *const u8, len: usize) {
+    #[cfg(target_os = "linux")]
+    if len >= HUGE_PAGE_THRESHOLD {
+        const PAGE: usize = 4096;
+        let start = (ptr as usize).next_multiple_of(PAGE);
+        let end = (ptr as usize + len) & !(PAGE - 1);
+        if end > start {
+            // SAFETY: `[start, end)` lies inside an allocation of `len` bytes
+            // at `ptr` that the caller owns, and is page aligned as madvise
+            // requires. MADV_HUGEPAGE does not change the memory's contents or
+            // validity; on failure (EINVAL when THP is compiled out, etc.) the
+            // region is simply left as it was, so the result is ignored.
+            unsafe {
+                libc::madvise(start as *mut libc::c_void, end - start, libc::MADV_HUGEPAGE);
+            }
+        }
+    }
+    #[cfg(not(target_os = "linux"))]
+    let _ = (ptr, len);
+}
+
+/// `Vec::with_capacity(count)` for a buffer about to be filled in bulk, with
+/// huge-page advice when it is large (see the module docs).
+#[inline]
+pub(crate) fn vec_for_bulk<T>(count: usize) -> Vec<T> {
+    let v: Vec<T> = Vec::with_capacity(count);
+    advise_huge_pages(
+        v.as_ptr().cast::<u8>(),
+        v.capacity().saturating_mul(core::mem::size_of::<T>()),
+    );
+    v
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn bulk_vec_is_an_ordinary_vec() {
+        for count in [0usize, 1, 1000, HUGE_PAGE_THRESHOLD / 4 + 3] {
+            let mut v: Vec<u32> = vec_for_bulk(count);
+            assert!(v.capacity() >= count);
+            v.extend((0..count as u32).map(|i| i.wrapping_mul(2654435761)));
+            assert!(
+                v.iter()
+                    .enumerate()
+                    .all(|(i, &x)| x == (i as u32).wrapping_mul(2654435761))
+            );
+        }
+    }
+}

crates/clawhdf5-format/src/chunked_read.rs

@@ -277,6 +277,8 @@ pub(crate) fn alloc_output(len: usize) -> Result<Vec<u8>, FormatError> {
     if ptr.is_null() {
         return Err(failed());
     }
+    // Before anything writes to it, so a large buffer faults in huge pages.
+    crate::bulk_alloc::advise_huge_pages(ptr, len);
     // SAFETY: `ptr` came from the global allocator with the layout of
     // `[u8; len]`, which is exactly what `Vec<u8>` with capacity `len` frees;
     // all `len` bytes are initialised (zero).

crates/clawhdf5-format/src/data_read.rs

@@ -180,7 +180,9 @@ fn read_raw_data_full_impl(
                 });
             }
             ensure_len(file_data, addr, sz)?;
-            Ok(file_data[addr..addr + sz].to_vec())
+            let mut out = crate::bulk_alloc::vec_for_bulk(sz);
+            out.extend_from_slice(&file_data[addr..addr + sz]);
+            Ok(out)
         }
         DataLayout::Chunked { .. } => read_chunked_data(
             file_data,
@@ -765,7 +767,7 @@ fn get_size(dt: &Datatype) -> usize {
 fn native_le_to_vec<T: Copy>(raw: &[u8], count: usize) -> Vec<T> {
     let bytes = count * core::mem::size_of::<T>();
     debug_assert!(bytes <= raw.len());
-    let mut result: Vec<T> = Vec::with_capacity(count);
+    let mut result: Vec<T> = crate::bulk_alloc::vec_for_bulk(count);
     // SAFETY: `result` has capacity for `count` values of `T`, i.e. `bytes`
     // bytes; `raw` holds at least `bytes` bytes (callers derive `count` from
     // `raw.len() / size_of::<T>()`); the regions cannot overlap because
@@ -803,7 +805,7 @@ pub fn read_as_f64(raw: &[u8], datatype: &Datatype) -> Result<Vec<f64>, FormatEr
     }
 
     let order = get_byte_order(datatype);
-    let mut result = Vec::with_capacity(count);
+    let mut result = crate::bulk_alloc::vec_for_bulk(count);
     if let Datatype::FloatingPoint { .. } = datatype {
         let format = FloatFormat::of(datatype)?;
         for chunk in raw.chunks_exact(elem_size) {
@@ -955,7 +957,7 @@ pub fn read_as_i64(raw: &[u8], datatype: &Datatype) -> Result<Vec<i64>, FormatEr
     }
 
     let order = get_byte_order(datatype);
-    let mut result = Vec::with_capacity(count);
+    let mut result = crate::bulk_alloc::vec_for_bulk(count);
     for i in 0..count {
         let chunk = &raw[i * elem_size..(i + 1) * elem_size];
         result.push(decode_scalar(chunk, datatype, &order)?.to_i64());
@@ -985,7 +987,7 @@ pub fn read_as_u64(raw: &[u8], datatype: &Datatype) -> Result<Vec<u64>, FormatEr
     }
     let count = raw.len() / elem_size;
     let order = get_byte_order(datatype);
-    let mut result = Vec::with_capacity(count);
+    let mut result = crate::bulk_alloc::vec_for_bulk(count);
     for i in 0..count {
         let chunk = &raw[i * elem_size..(i + 1) * elem_size];
         result.push(decode_scalar(chunk, datatype, &order)?.to_u64());
@@ -1018,14 +1020,17 @@ pub fn read_as_f32(raw: &[u8], datatype: &Datatype) -> Result<Vec<f32>, FormatEr
     // Little-endian IEEE half precision (numpy float16): widen directly.
     if is_native_le_float(datatype, FloatFormat::Half) {
         let (halves, _) = raw[..count * 2].as_chunks::<2>();
-        return Ok(halves
-            .iter()
-            .map(|&b| f16_bits_to_f32(u16::from_le_bytes(b)))
-            .collect());
+        let mut result = crate::bulk_alloc::vec_for_bulk(count);
+        result.extend(
+            halves
+                .iter()
+                .map(|&b| f16_bits_to_f32(u16::from_le_bytes(b))),
+        );
+        return Ok(result);
     }
 
     let order = get_byte_order(datatype);
-    let mut result = Vec::with_capacity(count);
+    let mut result = crate::bulk_alloc::vec_for_bulk(count);
     if let Datatype::FloatingPoint { .. } = datatype {
         let format = FloatFormat::of(datatype)?;
         for chunk in raw.chunks_exact(elem_size) {
@@ -1114,7 +1119,7 @@ pub fn read_as_i32(raw: &[u8], datatype: &Datatype) -> Result<Vec<i32>, FormatEr
     }
 
     let order = get_byte_order(datatype);
-    let mut result = Vec::with_capacity(count);
+    let mut result = crate::bulk_alloc::vec_for_bulk(count);
     for i in 0..count {
         let chunk = &raw[i * elem_size..(i + 1) * elem_size];
         result.push(decode_scalar(chunk, datatype, &order)?.to_i32());

crates/clawhdf5-format/src/lib.rs

@@ -61,6 +61,7 @@ pub mod attribute;
 pub mod attribute_info;
 pub mod btree_v1;
 pub mod btree_v2;
+mod bulk_alloc;
 pub mod checksum;
 pub mod chunk_cache;
 mod chunk_grid;