Module prefetch 

Cache-line prefetch hints and a lookahead cursor for software-pipelined scans.

A scan whose per-item work waits on a cache miss can issue that miss for an item some distance ahead of consuming it, so several misses are in flight at once. Lookahead hands the scan each item that distance ahead of consuming it, and prefetch and prefetch_lines issue the hints.

Examples

use commonware_utils::prefetch::Lookahead;

let items = vec![1u64, 2, 3, 4, 5];
let mut hinted = Vec::new();
let mut ahead = Lookahead::new(2);
let mut scan = items.into_iter();
loop {
    // Each item comes up once, two items before the scan consumes it.
    for item in ahead.advance(scan.as_slice()) {
        hinted.push(*item);
    }
    let Some(item) = scan.next() else { break };
    assert!(hinted.contains(&item));
}
assert_eq!(hinted, [1, 2, 3, 4, 5]);

Structs

Lookahead

A cursor that runs a fixed distance ahead of a scan, handing out each item that many items before the scan consumes it, so the caller can prefetch what the item’s work reads.

Constants

ENABLED

Whether prefetch issues a hint on this target. Hint sites return early when it does not, so the overflow and bounds checks on the addresses they compute are compiled out with the hint.

Functions

prefetch

Hint the CPU to start loading the cache line holding ptr, without waiting for it. A prefetch never faults and has no architectural effect, so ptr may be dangling or out of bounds. A no-op on targets other than x86_64 and aarch64, and under Miri.

prefetch_lines

Hint every cache line that the len values of T at ptr intersect, at most max_lines of them from the first (see prefetch).