Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -452,7 +452,8 @@ comment claiming they do.
- **Erasure coding.** A page with no peers keeps a redundancy fragment, so a
partial corruption is still recoverable from the single copy it has. The
fragment is local to its page and is empty whenever the page has peers, which
is why the data term measures exactly 3.00x at three replicas.
is why a page written in large pieces measures exactly 3.00x at three replicas, with no
fragment on top.
- **Striped payload, if you ask for it.** `stripe_redundancy_units` spreads a
page across its replicas as fixed-size units instead of copying it to each, so
the store holds `replica_count / (replica_count - stripe_redundancy_units)` of
Expand Down Expand Up @@ -483,12 +484,16 @@ At three replicas with the metadata counted, measured at 26-character keys:
| object size | objects | amplification | data-only figure |
|---:|---:|---:|---:|
| 64 KiB | 1,000 | **3.01x** | 3.00x |
| 4 KiB | 4,000 | **3.08x** | 3.00x |
| 1 KiB | 8,000 | **3.32x** | 3.02x |
| 4 KiB | 4,000 | **3.14x** | 3.05x |
| 1 KiB | 8,000 | **3.34x** | 3.02x |

The data term is exactly **3.00x** -- the replication floor for a store that
copies every page to every replica -- so everything above it is metadata, which
is **290 bytes an object plus 164,232 fixed** whatever the object size.
The data term has a floor of **3.00x** -- the replication floor for a store that
copies every page to every replica -- and reads exactly that when a page is written in
large pieces (the 64 KiB row). A page grown by many small appends also holds up to a
sixteenth of its length in spare room, so the allocator is asked to grow it about once per
6.25% rather than once per append (`reserve_page_growth`); that is the 0.05x on the 4 KiB
row. What sits above the data term is metadata, which is **290 bytes an object plus 164,232
fixed** whatever the object size.

**What that 3.00x buys depends on where the replicas are, and the figure cannot tell you.**
Three copies measure 3.00x whether they are three `BTreeMap`s on one heap or three copies in
Expand Down Expand Up @@ -529,7 +534,8 @@ Those two numbers are a line, fitted from measurements at three object counts by
if this file disagrees with the tree.

A store that stripes moves the data term itself, to **1.5x** at three replicas and
one unit of redundancy -- which is the least any layout can hold and still survive a
one unit of redundancy (1.53x for a page built by 1 KiB appends, which carries its
growth headroom) -- which is the least any layout can hold and still survive a
loss. Every replica holds one unit of each stripe group, so keeping `p` units of
redundancy over `R` replicas costs `R / (R - p)`, which is smallest at one unit; with
no redundancy nothing is recoverable, and the only way further down is more replicas,
Expand All @@ -538,7 +544,7 @@ which is more hardware rather than less space.
replicas to eight and fails if any of them undercuts that.

Counted with the metadata, a thousand objects of 1 KiB measure
**1.97x striped against 3.46x replicated**, both read out of `footprint_audit()` on a
**2.00x striped against 3.54x replicated**, both read out of `footprint_audit()` on a
store nothing has read back yet. What separates the total from the 1.5x data term is the
metadata line above, which striping does not change: the same 290 bytes an object either
way. Striping moves the payload and nothing else.
Expand Down
13 changes: 9 additions & 4 deletions docs/footprint.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,13 @@ Measured at three replicas, 26-character keys, with the metadata counted:
| object size | objects | amplification | data-only figure |
|---:|---:|---:|---:|
| 64 KiB | 1,000 | **3.01x** | 3.00x |
| 4 KiB | 4,000 | **3.08x** | 3.00x |
| 1 KiB | 8,000 | **3.32x** | 3.02x |
| 4 KiB | 4,000 | **3.14x** | 3.05x |
| 1 KiB | 8,000 | **3.34x** | 3.02x |

A page written in large pieces holds exactly the floor (the 64 KiB row). A page grown by many
small appends also holds up to a sixteenth of its length in spare room, because the allocator is
asked to grow it about once per 6.25% instead of once per append -- that is the 0.05x above the
floor on the 4 KiB row.

Reproduce any row with the measurement harness:

Expand All @@ -33,8 +38,8 @@ MEASURE_OBJECTS=8000 MEASURE_SIZE=1024 cargo test --release --lib \

**Lowering `replica_count` does not reach 1.0x.** A page with no peers keeps a
redundancy fragment so that a partial corruption is still recoverable from the
single copy it has, and a page with peers does not — which is why the data term
above is exactly 3.00 rather than something above it. Measured at one replica:
single copy it has, and a page with peers does not — which is why a page written in
large pieces is exactly 3.00 rather than something above it. Measured at one replica:

| bytes in the page | fragment | split | overhead |
|---:|---:|---:|---:|
Expand Down
92 changes: 72 additions & 20 deletions src/object_store_regression_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3048,6 +3048,50 @@ fn object_inventory_pages_metadata_and_placement() {
assert_eq!(budgeted.next_marker.as_deref(), Some("logs/a"));
}

#[test]
fn a_page_filled_by_small_appends_reallocates_rarely_and_holds_bounded_slack() {
// A page used to ask the allocator for exactly the bytes each append added, so every append
// could copy the whole page. The growth is geometric now, with headroom of a sixteenth of what
// the page holds. Two claims, because each alone is easy to satisfy: appends must not
// reallocate per write (doubling would pass that), and the spare room must stay bounded
// (reserving exactly would pass that).
const APPENDS: usize = 900;
const WIDTH: usize = 1024;
let mut chunk = MatrixReplicaService::new();
let page_id = PageId {
chunk_id: ChunkId::new(0, 992).unwrap(),
page_index: 0,
};
let mut expected: Vec<u8> = Vec::new();
let mut capacities = std::collections::BTreeSet::new();
for append in 0..APPENDS {
let bytes: Vec<u8> = (0..WIDTH).map(|i| (append * 31 + i) as u8).collect();
chunk
.write_chunk(page_id.clone(), expected.len() as u64, &bytes)
.unwrap();
expected.extend_from_slice(&bytes);
let page = chunk.pages_local().get(&page_id).unwrap();
capacities.insert(page.data.capacity());
}
let page = chunk.pages_local().get(&page_id).unwrap();
assert_eq!(page.data.as_slice(), expected.as_slice(), "the bytes are unchanged");

let len = page.data.len();
let capacity = page.data.capacity();
assert!(
capacity <= len + len / 16 + WIDTH,
"spare room must stay near a sixteenth of the page: capacity {capacity} for {len} bytes"
);
// One distinct capacity per reallocation. Growing to 900 KiB by a sixteenth each time is about
// eighty steps; the exact-reserve policy this replaced took one per append.
println!("PAGE_GROWTH appends={APPENDS} reallocations={} slack_bytes={}", capacities.len(), capacity - len);
assert!(
capacities.len() <= APPENDS / 8,
"{} reallocations for {APPENDS} appends: growth is not geometric",
capacities.len()
);
}

#[test]
fn a_chunk_checksum_is_the_hash_of_its_payload_however_the_write_arrived() {
// `write_chunk` resumes the FNV-1a fold over the appended bytes instead of re-hashing the
Expand Down Expand Up @@ -43966,21 +44010,27 @@ fn a_store_holds_one_and_a_half_copies_of_its_payload_when_it_stripes() {
striped_logical, plain_logical,
"both stores must have been given the same logical bytes for the figures to compare"
);
assert_eq!(
plain_held * 1000 / plain_logical,
3000,
"three-way replication holds three copies, and this is the figure the payload floor \
has always reported"
// THE FLOOR, PLUS THE HEADROOM A GROWING PAGE CARRIES. Three copies is the floor and the
// figure never goes below it; a page built by small appends also holds up to a sixteenth of
// its length in spare room (`reserve_page_growth`), so the figure sits in a band above it.
// Pinned as that band rather than as the floor, because the floor alone is no longer what a
// store built by 1 KiB appends measures.
let plain_permille = plain_held * 1000 / plain_logical;
let striped_permille = striped_held * 1000 / striped_logical;
assert!(
(3000..=3188).contains(&plain_permille),
"three-way replication holds three copies plus at most a sixteenth of headroom: \
{plain_permille}"
);
assert_eq!(
striped_held * 1000 / striped_logical,
1500,
"a striped store should hold one and a half"
assert!(
(1500..=1594).contains(&striped_permille),
"a striped store should hold one and a half copies plus at most a sixteenth of \
headroom: {striped_permille}"
);
assert_eq!(
striped_held * 2,
plain_held,
"exactly half, asserted as a relation so it cannot drift into a near miss: \
// Half, within the headroom. Asserted as a relation so it cannot drift into a near miss.
assert!(
(striped_held * 2).abs_diff(plain_held) * 1000 / plain_held <= 63,
"striping should hold half what replication does, give or take headroom: \
{striped_held} against {plain_held}"
);
}
Expand Down Expand Up @@ -44034,10 +44084,11 @@ fn a_striped_store_is_still_striping_after_a_snapshot_round_trip() {
.get(key)
.unwrap_or_else(|| panic!("the audit should report {key}"))
};
assert_eq!(
get("replica.data.capacity") * 1000 / get("logical.written"),
1500,
"a restored striped store should still hold one and a half copies"
let restored_permille = get("replica.data.capacity") * 1000 / get("logical.written");
assert!(
(1500..=1594).contains(&restored_permille),
"a restored striped store should still hold one and a half copies plus at most a \
sixteenth of headroom: {restored_permille}"
);
}

Expand Down Expand Up @@ -47632,9 +47683,10 @@ fn the_published_striped_amplification_is_the_one_this_tree_produces() {
// The data terms, so a total that happened to match cannot hide a layout that did not
// take: 1.5x against 3.0x is the layout doing its job, and 1,504 rather than 1,500 is
// the last page of 8,000 objects not filling a whole stripe group.
assert_eq!(
replicated_data, 3000,
"three-way replication holds three copies"
assert!(
(3000..=3188).contains(&replicated_data),
"three-way replication holds three copies plus at most a sixteenth of headroom: \
{replicated_data}"
);
assert!(
(1500..=1560).contains(&striped_data),
Expand Down
29 changes: 24 additions & 5 deletions src/services/chunk/chunk_writes.inc.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,27 @@
// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 MatrixArkAI
/// Room for a page payload to grow to `needed_len`, with headroom proportional to what it holds.
///
/// A page filled by many small appends used to ask for EXACTLY the bytes each append added, so
/// the allocator was asked to grow the buffer on every write and, once it could not extend it in
/// place, copied the whole page: 33% of a 256 KiB-put profile was that copy, and 7% of a 1 KiB
/// one. Doubling would amortise it but a page then holds up to ~1.9x the bytes it stores
/// (measured 163 MB of capacity for 87 MB of data at three replicas).
///
/// A sixteenth of the current length sits between the two. Growth is geometric, so a page
/// reallocates about once per 6.25% it grows rather than once per append, and the spare room is
/// bounded at 6.25% of the page -- a figure that does not depend on how many writes built it.
/// A write that grows the page by more than that asks for exactly what it needs, so a page
/// filled by large objects carries no spare room at all.
pub(crate) fn reserve_page_growth(payload: &mut Vec<u8>, needed_len: usize) {
if needed_len <= payload.capacity() {
return;
}
let len = payload.len();
let target = needed_len.max(len.saturating_add(len / 16));
payload.reserve_exact(target.saturating_sub(len));
}

impl MatrixReplicaService {
pub fn write_chunk(
&mut self,
Expand Down Expand Up @@ -47,10 +69,7 @@ impl MatrixReplicaService {
let checksum_before_write = chunk.checksum_fnv1a64;
if end_index > chunk.data.len() {
let payload = std::sync::Arc::make_mut(&mut chunk.data);
// reserve_exact, not resize's doubling: a chunk filled by many small
// writes otherwise holds ~1.9x the bytes it stores (measured 163 MB
// of capacity for 87 MB of data at three replicas).
payload.reserve_exact(end_index.saturating_sub(payload.len()));
reserve_page_growth(payload, end_index);
payload.resize(end_index, 0);
}
std::sync::Arc::make_mut(&mut chunk.data)[start_index..end_index].copy_from_slice(data);
Expand Down Expand Up @@ -345,7 +364,7 @@ impl MatrixReplicaService {
})?;
if projected_len_index > chunk.data.len() {
let payload = std::sync::Arc::make_mut(&mut chunk.data);
payload.reserve_exact(projected_len_index.saturating_sub(payload.len()));
reserve_page_growth(payload, projected_len_index);
payload.resize(projected_len_index, 0);
}
for (offset, data) in coalesced {
Expand Down
Loading