Struct MappedFile 

pub struct MappedFile { /* private fields */ }

A file’s bytes in array storage: on a Mac with a GPU, the file is memory-mapped and wrapped as GPU-visible memory without a copy, so arrays made from it are views whose pages are read when first touched (by the CPU or the GPU). Elsewhere the file is read into memory. The mapping lives as long as any array made from it.

The file must not be modified (written or truncated, by this or another process) while it is mapped: arrays made from it would change underneath their readers (undefined behaviour), and reads past a truncated end raise SIGBUS. Map only files nothing writes while they are in use, such as model weights.

use nuvec_core::{DType, MappedFile};

let path = std::env::temp_dir().join("nuvec-mapped-file-doc.bin");
let bytes: Vec<u8> = [1.0f32, 2.0, 3.0, 4.0].iter().flat_map(|v| v.to_le_bytes()).collect();
std::fs::write(&path, &bytes).unwrap();
let file = MappedFile::open(&path)?;
let a = file.array(4, DType::F32, &[3])?; // bytes 4..16, no copy
assert_eq!(a.to_vec::<f32>()?, vec![2.0, 3.0, 4.0]);

Implementations

impl MappedFile

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Maps (or reads) the file at path. The file must not be modified while it is mapped (see MappedFile).

pub fn mapping_size(len: u64) -> u64

The bytes mapping a file of len bytes holds in the GPU allocator’s mapped statistic: the whole file, rounded up to pages.

pub fn copy_size(len: u64) -> u64

The bytes storage of len bytes (as MappedFile::read_ranges allocates) holds in the GPU allocator’s active statistic: its size class.

pub fn headroom() -> Option<u64>

The bytes that may still be mapped or allocated before the GPU’s memory limit (memory_limit − active − mapped), or None without a GPU.

pub fn len(&self) -> usize

The file’s size in bytes.

pub fn is_empty(&self) -> bool

Whether the file is empty.

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

The file’s bytes.

pub fn read_ranges( path: impl AsRef<Path>, ranges: &[(u64, usize, usize)], len: usize, ) -> Result<Self>

Reads parts of the file at path into new array storage of len bytes, without mapping it: each (file_offset, offset, n) of ranges puts the file’s bytes file_offset..file_offset + n at offset..offset + n. For files whose arrays are not aligned to their element sizes (safetensors written without header padding, as MLX writes them): the ranges are placed so that every array is aligned, and arrays made from the result are views of it. Bytes outside the ranges are unspecified.

The ranges must be in increasing order of offset and must not overlap. They are read with positioned reads in chunks of 16 MiB, on up to 8 threads (one per 64 MiB read), straight into the storage: from the page cache this runs at memory bandwidth, and nothing but the storage is allocated (the file is not mapped).

use nuvec_core::{DType, MappedFile};

let path = std::env::temp_dir().join("nuvec-read-ranges-doc.bin");
// One padding byte, then three f32s: misaligned in the file.
let mut bytes = vec![0u8];
bytes.extend([1.0f32, 2.0, 3.0].iter().flat_map(|v| v.to_le_bytes()));
std::fs::write(&path, &bytes).unwrap();
let file = MappedFile::read_ranges(&path, &[(1, 0, 12)], 12)?;
assert_eq!(file.array(0, DType::F32, &[3])?.to_vec::<f32>()?, vec![1.0, 2.0, 3.0]);

pub fn array( &self, offset: usize, dtype: DType, shape: &[usize], ) -> Result<Array>

A row-major array of dtype and shape stored at byte offset: a view of the file if offset is a multiple of the element size, otherwise a copy.

Trait Implementations

impl Clone for MappedFile

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for MappedFile

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

Formats the value using the given formatter.