Skip to main content

Module pin

Module pin 

Source
Expand description

What a slice keeps alive (plan sections 3.15 and 8, R3). A Bytes slice of a decoded run, or of an input’s own bytes, keeps the whole buffer alive, with its charge, for as long as the slice lives: on the corpus one value kept past its input’s handles kept the input’s whole decoded run alive (up to 69.4 MB), through its strings and byte arrays and through the node lists that name its keys, whose strings are slices of the file too.

So a value an object read returns (crate::object::ObjectRef) and each typetree a SerializedFile parses copy their slices out, into one buffer of their own charged to the same meter, when the slices would keep much more than themselves alive: when L - S >= max(1 MiB, 4 S) (worth_copying), L the length of the buffer they are slices of (the file’s crate::files::SerializedFile::pinned) and S the distinct bytes they span. Below that, a kept value keeps at most max(S + 1 MiB, 5 S) of the buffer alive, its own slices included, and a copy would cost more than it frees. The copy’s charge rides in its Bytes, its owner record included (crate::budget::charged_bytes), so it returns when the last slice of it drops. A refused copy leaves the slices in place. Legacy reads and parses proceed after a refusal, while a lossless read propagates it on the caller’s meter. Copies counts what was copied, per file. The other slices the core hands out are not copied, and each keeps its whole buffer alive as any slice does: crate::object::ObjectRef::raw_data, crate::files::BundleFile::entry_bytes and crate::files::BundleFile::entry_range, crate::files::SerializedFile::data, and the value of crate::walk::read_typetree, whose caller hands it the buffer.

Each byte once. The copy holds each byte of the buffer that some slice names once, however many slices name it, and each slice becomes the slice of the copy at the same place in those bytes: slices that were one buffer (an address and a length) are one buffer of the copy, and slices that overlapped overlap there as they did. So what a tree’s compile reads and counts, which goes by buffer (typetree::tree::names: rows that share a buffer cost what one row naming it costs), is the same for its copied rows as for its rows read from a short run, and a name 300 rows share is held once (perf stage 2’s review: each slice was copied on its own, so 300 rows naming one 1,000-byte string held 300 copies of it, and their compile, which no longer saw one buffer, counted 600,000 bytes of work where the same file read lazily counted 12,000). To find those bytes the slices are listed by where they lie, sorted, and merged where they overlap or touch: a table of two words a slice, charged to the meter while the copy is made, whose refusal is the copy’s.

Structs§

Copies
What a file’s reads and its parse copied out of the buffer its bytes are a slice of (module docs; plan section 8, R3).

Constants§

UNPIN_MIN
The least a copy frees: slices of a buffer this long or shorter are never copied.

Functions§

worth_copying
Whether slices of s bytes, of a buffer of pinned bytes, are copied out: pinned - s >= max(1 MiB, 4 s), and there is something to copy.