Paletted container access: skip the storage revalidation a section already did

BlockSection::get and set check the section index and the state id once,
then read and write through new PackedStorage::read/write, which skip the
storage-level bounds and value checks and the Result that get/set keep for
external callers. A section index is below 4,096 and a palette id always
fits the width bits_for_palette chose; both methods debug_assert that
contract. Used for the hot read, the hot write and the growth re-encode.

Benchmark (ignored tests, best of alternating-order rounds, fast profile):
BlockSection::set 13.15 -> 9.12 ns/write (1.44x), get 2.33 -> 1.45 ns/read
(1.61x). See docs/performance/paletted-container-access-results.md.
This commit is contained in:
rdbtCVS
2026-10-17 23:23:15 +01:00
parent 56a251eb13
commit 5c55e7d855
3 changed files with 82 additions and 17 deletions
+22
View File
@@ -88,6 +88,28 @@ impl PackedStorage {
Ok(((self.words[word] >> shift) & self.mask) as u32)
}
/// Reads `index` without a bounds check. Callers use this once they hold a
/// slice length or a section index they have already validated.
/// `index` must be less than `len`.
pub fn read(&self, index: usize) -> u32 {
debug_assert!(index < self.len);
let word = index / self.per_word;
let shift = (index % self.per_word) * usize::from(self.bits);
((self.words[word] >> shift) & self.mask) as u32
}
/// Writes `value` at `index` without revalidating either. `index` must be
/// less than `len` and `value` must fit `bits`, which holds for a section
/// palette index from the same container. Returns the previous value.
pub fn write(&mut self, index: usize, value: u32) -> u32 {
debug_assert!(index < self.len && u64::from(value) <= self.mask);
let word = index / self.per_word;
let shift = (index % self.per_word) * usize::from(self.bits);
let old = ((self.words[word] >> shift) & self.mask) as u32;
self.words[word] = (self.words[word] & !(self.mask << shift)) | (u64::from(value) << shift);
old
}
/// Validation fails before mutation. Writes accept nonnegative Java ints;
/// imported 32-bit words may still decode to any u32 bit pattern.
pub fn set(&mut self, index: usize, value: u32) -> Result<u32, StorageError> {
+40 -8
View File
@@ -442,7 +442,7 @@ impl<'r> BlockSection<'r> {
if index >= 4096 {
return Err(invalid("section index out of bounds"));
}
let id = self.storage.as_ref().map_or(0, |s| s.get(index).unwrap());
let id = self.storage.as_ref().map_or(0, |s| s.read(index));
Ok(self.palette[id as usize])
}
pub fn set(&mut self, index: usize, state: BlockStateId) -> io::Result<BlockStateId> {
@@ -454,7 +454,7 @@ impl<'r> BlockSection<'r> {
}
// The slot at `index` is the old state's id, so no palette lookup is
// needed for it; only the new state has to be resolved.
let old_id = self.storage.as_ref().map_or(0, |s| s.get(index).unwrap());
let old_id = self.storage.as_ref().map_or(0, |s| s.read(index));
let old = self.palette[old_id as usize];
if old == state {
return Ok(old);
@@ -481,7 +481,7 @@ impl<'r> BlockSection<'r> {
.map_err(|e| invalid(e.to_string()))?;
if let Some(old) = &self.storage {
for i in 0..4096 {
storage.set(i, old.get(i).unwrap()).unwrap();
storage.write(i, old.read(i));
}
}
self.storage = Some(storage);
@@ -493,11 +493,7 @@ impl<'r> BlockSection<'r> {
}
}
};
self.storage
.as_mut()
.unwrap()
.set(index, id)
.map_err(|e| invalid(e.to_string()))?;
self.storage.as_mut().unwrap().write(index, id);
self.counts[old_id as usize] -= 1;
self.counts[id as usize] += 1;
if self.counts[old_id as usize] == 0 {
@@ -823,5 +819,41 @@ mod tests {
times[1][0],
times[0][0] / times[1][0]
);
let mut get_times = [Vec::new(), Vec::new()];
for round in 0..ROUNDS {
for optimized in [round % 2 == 0, round % 2 != 0] {
let started = Instant::now();
let mut acc = 0u32;
for &(index, _) in &ops {
let state = if optimized {
fast.get(black_box(index)).unwrap()
} else {
baseline_get(&base, black_box(index)).unwrap()
};
acc ^= state.0;
}
black_box(acc);
if round > 0 {
get_times[usize::from(optimized)]
.push(started.elapsed().as_secs_f64() * 1e9 / OPS as f64);
}
}
}
for values in &mut get_times {
values.sort_by(f64::total_cmp);
}
println!(
"section get median: baseline {:.3} ns/op optimized {:.3} ns/op speedup {:.3}x",
median(&get_times[0]),
median(&get_times[1]),
median(&get_times[0]) / median(&get_times[1])
);
println!(
"section get best: baseline {:.3} ns/op optimized {:.3} ns/op speedup {:.3}x",
get_times[0][0],
get_times[1][0],
get_times[0][0] / get_times[1][0]
);
}
}
@@ -5,8 +5,9 @@ chunk workers: light and mesh workers unpack a section's 4,096 cells before
propagating or meshing, and world-generation workers write one block at a time
through `BlockSection::set`.
Two redundant lookups were removed from the write path, and the palette dispatch
was hoisted in the bulk readers.
The write path resolved the old cell and probed the palette three times; the
bulk readers dispatched the palette per cell; and the storage layer revalidated
indices and values a section had already checked. All three are addressed.
## Changes
@@ -19,6 +20,14 @@ now read straight from storage, and the incoming state is resolved with a single
map probe. The palette-reuse, free-slot and growth paths are unchanged, so the
encoded palette, counts, free list and NBT output stay identical.
`BlockSection::get` and `set` validate the section index and the state id once,
then read and write through `PackedStorage::read`/`write`
(`crates/horizon-core/src/storage.rs`). These skip the storage-level bounds and
value checks and the `Result` that `PackedStorage::get`/`set` keep for external
callers: a section index is below 4,096 and a palette id always fits the width
`bits_for_palette` chose. Both new methods `debug_assert` their contract and are
used for the hot read, the hot write and the palette-growth re-encode.
`PalettedContainer::unpack` and `unpack_u16`
(`crates/horizon-core/src/paletted.rs`) matched on the palette variant inside the
per-cell loop. `Single`, `List` and `Global` are now dispatched once before the
@@ -40,19 +49,21 @@ and NBT before timing. Rounds alternate baseline/optimized order with `black_box
and report the median and best nanosecond- or microsecond-per-operation; the best
round is the estimate of uninterrupted CPU time on a contended machine.
`benchmark_section_get_set` uses a 32-state registry and 50,000 random writes per
round over a section whose palette grows through the 4- and 5-bit widths (24
distinct states); 51 rounds. `benchmark_unpack` fills a 4,096-entry list palette
(12 states) and the global palette, 2,000 calls per round, 25 rounds.
`benchmark_section_get_set` uses a 32-state registry and 50,000 random writes and
reads per round over a section whose palette grows through the 4- and 5-bit
widths (24 distinct states); 51 rounds. `benchmark_unpack` fills a 4,096-entry
list palette (12 states) and the global palette, 2,000 calls per round, 25
rounds.
AMD Ryzen 5 5600X, Linux x86_64, rustc 1.99.0, optimized `fast` profile,
nonincremental, no LTO:
| Operation | Original main | New | Speedup |
| --- | ---: | ---: | ---: |
| `BlockSection::set` | 12.73 ns/write | 11.37 ns/write | 1.12x |
| `unpack`, list palette | 1.956 us/call | 1.860 us/call | 1.05x |
| `unpack`, global palette | 2.255 us/call | 2.172 us/call | 1.04x |
| `BlockSection::set` | 13.15 ns/write | 9.12 ns/write | 1.44x |
| `BlockSection::get` | 2.33 ns/read | 1.45 ns/read | 1.61x |
| `unpack`, list palette | 1.910 us/call | 1.834 us/call | 1.04x |
| `unpack`, global palette | 2.270 us/call | 2.179 us/call | 1.04x |
The distinct-state differential test
`chunk::tests::set_matches_baseline_under_random_edits` drives the optimized