Low level IO abstraction. A typical implementation is unix. This abstraction is meant to be dead simple. Not a lot of documentation is required.

open_ro ~mapping_size ~mapping ~data returns a new read-only view of the sparse file, represented on disk by two files named mapping and data. The mapping file is expected to have size at least mapping_size (and the rest is ignored if the file is larger).

Close the underlying files.

read_exn t ~off ~len buffer writes into buffer the bytes from off to off+len.

Same as read_exn, the amount read is max_len if possible or at least min_len if reading more would step over a hole in the sparse file.

Returns the actually read length.

next_valid_offset t ~off returns Some off' such that off' is the smallest readable offset larger or equal to off. This enables jumping over a sparse hole to the next compact range of data.

iter t f calls f on each (off,len) pair in mapping. Only used for testing and debugging.

It is guaranteed for the offsets to be iterated in monotonic order.

It is guaranteed that entries don't overlap.

The exceptions raised by f are caught and returned (as long as they are known by Errs).