Skip to content

Commit 288dfd0

Browse files
committed
Docs: call the port bbtree++ and the original bbtree (Rust) throughout
1 parent 34952f3 commit 288dfd0

5 files changed

Lines changed: 42 additions & 43 deletions

File tree

‎FUTURE_WORK.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ building 100k maps of 32 `std::string` → 32-byte entries 26% faster (79 ns
9595
an insert to 58) in a prototype that fixed up `slots`' shifts and the paired
9696
entries' shift; 1M random inserts into one map gained nothing, their shifts
9797
overlapping the leaf's cache misses. The bench's `build_many_100kx32` cell
98-
is where the port trails the Rust crate most (1.7x). Doing it means: a
98+
is where bbtree++ trails the Rust crate most (1.7x). Doing it means: a
9999
relocation trait with a fix-up after byte moves (`std::string` under
100100
libstdc++'s C++11 ABI, whose layout the ABI freezes: data pointer first,
101101
buffer at 16), fix-ups in every byte-moving path (`slots`' shifts and runs,
@@ -124,7 +124,7 @@ branch in `size()` for long strings only, and a second layout to test.
124124

125125
## From abseil's B-tree
126126

127-
`absl::btree_map` beats bbtree on 1k random u64 inserts (17 ns against
127+
`absl::btree_map` beats bbtree++ on 1k random u64 inserts (17 ns against
128128
30), `pop_first` (2×), `range64` (1.2-1.5×), and on building 4-entry maps
129129
and iterating them with `std::string` keys (CPP_MAPS.md). The Rust crate
130130
trails `BTreeMap` the same way, so these are design differences, not port
@@ -133,24 +133,24 @@ ones. Three of abseil's choices explain them:
133133
- **Root leaves sized to their entries.** abseil allocates a root leaf for
134134
as many slots as the map holds, and reallocates it larger as it grows,
135135
up to a full node: a 4-entry `std::string` → 32-byte map takes 88 bytes
136-
an entry against bbtree's 275, a full 1 KiB page. Building 1M such maps
136+
an entry against bbtree++'s 275, a full 1 KiB page. Building 1M such maps
137137
takes abseil 48-52 ns an entry against 66 (compact keys) to 77.
138138
Iterating them no longer shows it once the root leaf's loads follow a
139139
stride the prefetcher takes ([iteration](PORTING.md#p16-for_each-beside-iterators-for-rusts-folds)): compact keys 3.2 ns an entry against
140-
abseil's 3.5, `std::string` keys 5.6. For bbtree it means a root page of
140+
abseil's 3.5, `std::string` keys 5.6. For bbtree++ it means a root page of
141141
several sizes, a layout per capacity (the inline keys' area scales with
142142
it), and a copy each time the root grows; and it breaks the design's rule
143143
that "the root page stays the root", which the shared map's racing reads rely on, so it
144144
would be the unsync map's and set's only.
145145
- **Parent pointers.** abseil's iterator is a node and an index, stepping
146-
through parent pointers, so it stays in registers; bbtree's keeps a node
146+
through parent pointers, so it stays in registers; bbtree++'s keeps a node
147147
stack and its position in memory ([iteration](PORTING.md#p16-for_each-beside-iterators-for-rusts-folds)), which a 64-entry range scan and
148148
`pop_first`'s descent pay. Parent pointers cost 8 bytes a node and a
149149
write to every child an internal split or merge moves, and the shared
150150
map's nodes would need them kept under its latches.
151151
- **256-byte nodes.** abseil sizes nodes to about 256 bytes, so a u64 →
152152
u64 leaf holds 15 entries and an insert shifts at most 240 bytes. A
153-
bbtree leaf is at least 1 KiB (the design's floor, at least 12 keys): 55 u64
153+
bbtree++ leaf is at least 1 KiB (the design's floor, at least 12 keys): 55 u64
154154
entries, and up to 880 bytes shifted, which a 1k map in cache pays on
155155
every random insert and removal. Smaller leaves for small entries would
156156
need the 1 KiB floor and the inline-key area's sizing revisited.

‎bbtree-mmap/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# bbtree-mmap
22

3-
bbtree on disk: compact a bbtree map to a file, map it back into memory and
3+
bbtree++ on disk: compact a bbtree++ map to a file, map it back into memory and
44
query it at once, with the map's own lookups
55
([15-index-file.md](../design/15-index-file.md)).
66

‎bbtree-store/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# bbtree-store
22

33
An ordered store of byte strings that threads share, whose every byte lies
4-
in pages from its allocator: bbtree's shared map, whose keys point to their
4+
in pages from its allocator: bbtree++'s shared map, whose keys point to their
55
records, key and value, kept in chains of heap pages beside each leaf (a
66
leaf annex; [16-bbtree-store.md](../design/16-bbtree-store.md)). An
77
allocator that refuses pages past a budget bounds all the memory a store

‎bbtree/bench/COMPARISON.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ Both ran the same benchmark cells with the same inputs on one machine; see Setup
55

66
## Summary
77

8-
- **Integer keys:** the port is typically 1.0-1.3× as fast, up to 1.6×.
9-
- **String keys:** with compact strings the port is typically 1.05-1.3× as
8+
- **Integer keys:** bbtree++ is typically 1.0-1.3× as fast, up to 1.6×.
9+
- **String keys:** with compact strings bbtree++ is typically 1.05-1.3× as
1010
fast, up to 1.8×, and slower only building many 4-entry maps.
1111
- **The shared map:** faster on one thread, about 5% slower with 8 threads.
1212
- **bbtree-store:** inserts and gets are even or faster; scans are 13% slower.
@@ -88,11 +88,11 @@ fresh pages stalled it, 118 ns.
8888
The `1Mx4` and `100kx32` rows are the `tiny` suite's: a million maps of 4
8989
entries and 100k maps of 32, keys and 32-byte values.
9090

91-
With compact keys the port inserts, looks up and iterates strings faster
91+
With compact keys bbtree++ inserts, looks up and iterates strings faster
9292
than the Rust crate, builds 32-entry maps as fast, and trails only in
9393
building many 4-entry maps, where each map takes a full 1 KiB root page
9494
(FUTURE_WORK.md). With `std::string` keys it looks up faster but in
95-
32-entry maps, and inserts and builds slower (see "Where the port
95+
32-entry maps, and inserts and builds slower (see "Where bbtree++
9696
trails"). Iterating maps of 4
9797
trailed until the root leaf's entries went four a round (PORTING.md,
9898
[iteration](../../PORTING.md#p16-for_each-beside-iterators-for-rusts-folds)): one load per entry, stepping by a page from map to map, which
@@ -152,7 +152,7 @@ and churn rows.
152152
- **C++:** Clang 15, `--preset bench` (`-O3 -march=native`, LTO), mimalloc
153153
3.3.2 (PORTING.md, [the bench's allocator](../../PORTING.md#p17-the-benchs-allocator-mimalloc-332-behind-operator-new)).
154154
- **Inputs:** the same keys, values, orders and probes: `bbtree-bench
155-
self-check` pins the port's generators to the Rust bench's (PORTING.md,
155+
self-check` pins the C++ bench's generators to the Rust bench's (PORTING.md,
156156
[bench inputs](../../PORTING.md#p19-bench-inputs-the-rust-benchs-key-for-key)).
157157
- **Runs:** one per cell, each in a fresh process (AGENTS.md: no repeats to
158158
average noise away). Cells whose Rust runs varied by more than 10% across
@@ -186,12 +186,12 @@ four entries a round, and a checksum that folds, as the Rust bench's does
186186
| str-json_struct32_iterate_100kx32, `std::string` keys | **9.32** | 11.7 |
187187
| store scan, 1M, ns an entry | 23.0 | **20.3** |
188188

189-
† Across this session's windows 4.6-6.8 ns for the port and 4.9-5.7 for
189+
† Across this session's windows 4.6-6.8 ns for bbtree++ and 4.9-5.7 for
190190
the Rust bench; a rerun right after, with no compaction stall in the
191191
kernel, took 5.62 against 5.29. Before the four-a-round root leaves the
192-
port's took 7.2-9.0.
192+
bbtree++'s took 7.2-9.0.
193193

194-
## Where the port trails, and why
194+
## Where bbtree++ trails, and why
195195

196196
- **`std::string` inserts (1.25-1.3×), small string maps' builds
197197
(1.4-1.65×):** libstdc++'s `std::string` is 32 bytes against `String`'s
@@ -216,9 +216,9 @@ port's took 7.2-9.0.
216216
0.64-0.71× the Rust crate's `String`, `std::string` keys 1.0-1.2×.
217217
- **The store's scan (1.5× → 1.13×):** the scan's visit and the record's
218218
`value()` were calls, a third more instructions an entry, so fewer
219-
entries' record misses overlapped ([store scans](../../PORTING.md#p31-a-store-scans-visit-inlines-into-the-maps-loop)). What is left is the port's 7
219+
entries' record misses overlapped ([store scans](../../PORTING.md#p31-a-store-scans-visit-inlines-into-the-maps-loop)). What is left is bbtree++'s 7
220220
more heap bytes an entry (87 against 80; [heads' records](../../PORTING.md#p24-a-leafs-head-keys-record-stays-put)). Long values (1.1-1.3×)
221221
are not looked into.
222222

223-
Everything else is within 10% or faster, mostly from the port's lookups
223+
Everything else is within 10% or faster, mostly from bbtree++'s lookups
224224
(`get_hit`/`get_miss` 0.63-0.99×) and the upsert path.

‎bbtree/bench/CPP_MAPS.md‎

Lines changed: 24 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,23 @@
22

33
`bbtree::unsync::bbtree_map` against `absl::btree_map`, `std::map` and
44
`std::unordered_map` (the bench's `std-hash`). COMPARISON.md compares
5-
the port with the Rust original; this file compares it with other C++ maps.
5+
bbtree++ with the Rust original; this file compares it with other C++ maps.
66

77
- **Machine and build:** as in COMPARISON.md (Ryzen 9 5950X, Clang 15,
88
`--preset bench`, mimalloc 3.3.2 with huge pages), abseil 20250814.2.
99
- **Run:** `bbtree-bench small tiny --key u64,str-16,str-json`, every map,
1010
122 cells, one run each in a fresh process, 21 s, load under 0.3.
1111
- **Sizes:** `small` runs every map at 1k entries and `tiny` on many small
1212
maps; `cpp`, the C++ bench's own suite, runs `ci`'s 1M and 10M workloads
13-
on every map (`ci` itself runs only bbtree and `std::map`, as in the Rust
13+
on every map (`ci` itself runs only bbtree++ and `std::map`, as in the Rust
1414
bench).
1515

1616
## 1k entries and many small maps, ns an operation (iterate, many maps: an entry)
1717

1818
Bold marks the fastest ordered map. The hash map has no order, so it has
1919
no `range64` or `pop_first`.
2020

21-
| cell | bbtree | absl btree | std::map | std::unordered_map |
21+
| cell | bbtree++ | absl btree | std::map | std::unordered_map |
2222
|---|--:|--:|--:|--:|
2323
| u64_u64_random_insert_1k | 29.8 | **17.2** | 22.6 | 10.7 |
2424
| u64_u64_sequential_insert_1k | **7.30** | 15.9 | 26.4 | 10.1 |
@@ -50,10 +50,9 @@ no `range64` or `pop_first`.
5050
## 1M and 10M entries, ns an operation (iterate: an entry)
5151

5252
`bbtree-bench cpp`, 76 cells, once each, 81 s, started at load 0.1 after
53-
the 5-minute load average had stayed under 0.3. Two earlier runs, on a
54-
machine busy with an IDE's indexing, are discarded.
53+
the 5-minute load average had stayed under 0.3.
5554

56-
| cell | bbtree | absl btree | std::map | std::unordered_map |
55+
| cell | bbtree++ | absl btree | std::map | std::unordered_map |
5756
|---|--:|--:|--:|--:|
5857
| u64_u64_random_insert_1M | **95.9** | 98.9 | 211 | 59.7 |
5958
| u64_u64_sequential_insert_1M | **9.83** | 33.9 | 78.7 | 61.0 |
@@ -72,21 +71,21 @@ machine busy with an IDE's indexing, are discarded.
7271
| str-json_u64_get_hit_1M | **274** | 432 | 689 | 153 |
7372
| str-json_u64_get_miss_1M | **168** | 413 | 812 | 117 |
7473

75-
† bbtree's runs of this cell ranged from 88 to 129 ns today (93.4 in
74+
† bbtree++'s runs of this cell ranged from 88 to 129 ns today (93.4 in
7675
COMPARISON.md; 110 on a rerun of the cell alone, at load 0.8); abseil's
7776
from 111 to 146. Unsettled: read it as about even.
7877

7978
## `compact_string` keys against `std::string` keys
8079

81-
`bbtree-unsync-compact` is bbtree's unsync map with `bbtree::compact_string`
80+
`bbtree-unsync-compact` is bbtree++'s unsync map with `bbtree::compact_string`
8281
keys (PORTING.md, [compact_string](../../PORTING.md#p29-compact_string-12-bytes-in-place-the-size-in-one-place)): 16 bytes, up to 12 in place, moved as bytes. The
8382
cell turns its keys into compact strings before it times anything.
8483
`bbtree-bench cpp --key str-16,str-json --map
8584
bbtree-unsync,bbtree-unsync-compact,absl-btree,std-btree`, one run each,
86-
started at load 0.3, with the root-leaf walk (PORTING.md, [iteration](../../PORTING.md#p16-for_each-beside-iterators-for-rusts-folds)). Rust is the Rust
87-
crate's bbtree with `String` keys, from COMPARISON.md.
85+
started at load 0.3, with the root-leaf walk (PORTING.md, [iteration](../../PORTING.md#p16-for_each-beside-iterators-for-rusts-folds)). bbtree (Rust),
86+
with `String` keys, is from COMPARISON.md.
8887

89-
| cell | `std::string` | `compact_string` | compact ÷ std | Rust | absl btree | std::map |
88+
| cell | `std::string` | `compact_string` | compact ÷ std | bbtree (Rust) | absl btree | std::map |
9089
|---|--:|--:|--:|--:|--:|--:|
9190
| str-16_u64_random_insert_1k | 58.9 | 39.1 | 0.66 | 46.6 | 106 | 105 |
9291
| str-16_u64_sequential_insert_1k | 32.1 | 16.1 | 0.50 | | 47.9 | 116 |
@@ -112,12 +111,12 @@ crate's bbtree with `String` keys, from COMPARISON.md.
112111
iterate in 5.6 ns an entry with `std::string` keys and 3.2 with
113112
`compact_string` keys (COMPARISON.md).
114113

115-
† bbtree's columns re-run after the checksum became a fold (PORTING.md, [iteration](../../PORTING.md#p16-for_each-beside-iterators-for-rusts-folds)).
116-
‡ Not comparable with the other runs: bbtree's maps of 4 take 1.1 GB of
114+
† bbtree++'s columns re-run after the checksum became a fold (PORTING.md, [iteration](../../PORTING.md#p16-for_each-beside-iterators-for-rusts-folds)).
115+
‡ Not comparable with the other runs: bbtree++'s maps of 4 take 1.1 GB of
117116
fresh pages, and with the machine's memory mostly page cache, getting huge
118117
pages stalled the kernel in compaction (29 stalls in one run of the cell,
119118
none in abseil's, which takes a third as much). The same cell took 78 ns
120-
with `std::string` keys earlier in the session; the two bbtree columns of
119+
with `std::string` keys earlier in the session; the two bbtree++ columns of
121120
this run stalled alike.
122121

123122
- **Writes:** an entry of a string → `u64` leaf shrinks from 49 bytes to
@@ -184,14 +183,14 @@ iterate in 5.6 ns an entry with `std::string` keys and 3.2 with
184183
The heap bytes a map holds after its build, divided by its entries:
185184
`bbtree-bench-memory cpp`, which counts the bytes mimalloc hands out
186185
(`mi_usable_size`) and frees, one run each. The counts don't depend on
187-
the machine's load. bbtree's string rows have the compact string that
186+
the machine's load. bbtree++'s string rows have the compact string that
188187
suits the keys (see above): `compact_string_24` (`bbtree-unsync-compact-24`,
189188
24 bytes, up to 20 in place) for `str-16`, whose keys it mostly holds in
190189
place, and the default `compact_string` (`bbtree-unsync-compact`, 16 bytes,
191190
a 4-byte size, up to 12 in place) for JSON keys. The other maps have
192191
`std::string` keys.
193192

194-
| cell | bbtree | absl btree | std::map | std::unordered_map | bbtree ÷ std::map |
193+
| cell | bbtree++ | absl btree | std::map | std::unordered_map | bbtree++ ÷ std::map |
195194
|---|--:|--:|--:|--:|--:|
196195
| u64_u64_random_insert_1k | 27.7 | **20.8** | 48.0 | 42.3 | 0.58 |
197196
| u64_u64_sequential_insert_1k | 24.6 | **18.1** | 48.0 | 42.3 | 0.51 |
@@ -209,7 +208,7 @@ a 4-byte size, up to 12 in place) for JSON keys. The other maps have
209208
node is 32 bytes of links and colour beside the entry's 16, mimalloc's
210209
48-byte size class. With `std::string` keys a node is 72 bytes, in the
211210
80-byte class, plus a heap buffer for each key past 15 bytes.
212-
- **bbtree's** `u64` entry is its 16 bytes and a 2-byte inline key: 18.5
211+
- **bbtree++'s** `u64` entry is its 16 bytes and a 2-byte inline key: 18.5
213212
bytes in the full leaves of a bulk build, 23.6 after ascending inserts,
214213
26.9 after random ones, which leave leaves about 70% full. abseil's
215214
nodes keep no inline keys and are 1-6 bytes an entry smaller.
@@ -220,15 +219,15 @@ a 4-byte size, up to 12 in place) for JSON keys. The other maps have
220219
48.8 against 55.2 in a bulk build, but 68.3 against 65.5 after
221220
sequential inserts. On JSON keys it takes 61.5 against 51.0. The
222221
2-byte-size variant is 1-2.4 bytes smaller than `compact_string` on
223-
every cell. With `std::string` keys bbtree takes
222+
every cell. With `std::string` keys bbtree++ takes
224223
76.9 bytes an entry on 1M JSON keys (0.93× std::map) and 72-106 on
225224
`str-16` at 1k.
226225
- **The Rust crate** takes the same bytes on every `u64` cell; with its
227226
24-byte `String` keys it takes 68.4 on 1M JSON keys.
228227

229228
## Against abseil's B-tree
230229

231-
- **bbtree is faster:**
230+
- **bbtree++ is faster:**
232231
- lookups: 1.5× on u64, 2-3× on 16-byte strings;
233232
- string inserts and upserts: 1.6×;
234233
- sequential inserts: 1.5-2×;
@@ -240,24 +239,24 @@ a 4-byte size, up to 12 in place) for JSON keys. The other maps have
240239
- many 4-entry maps: 1.6× to build, 2.4× to iterate; to iterate 1.6×
241240
since the walk reads root leaves four entries a round, which came after
242241
these tables
243-
(bbtree 5.6 ns an entry, `compact_string` keys 3.2; COMPARISON.md).
242+
(bbtree++ 5.6 ns an entry, `compact_string` keys 3.2; COMPARISON.md).
244243
- **About even:** removes, bulk builds, lookups in many small maps.
245-
- **At 1M and 10M:** bbtree misses 1.75-1.85× faster on u64 and 2.5× on
244+
- **At 1M and 10M:** bbtree++ misses 1.75-1.85× faster on u64 and 2.5× on
246245
JSON strings, hits 1.4-1.6× faster at 10M u64 and on strings, inserts
247246
JSON strings 1.5× and sequential u64 3.4× faster, and iterates 2.2×
248247
faster. abseil pops the first entry 2.1× faster and scans `range64`
249248
1.16× faster; random u64 inserts, removes, upserts and bulk builds are
250249
within 11%.
251250

252-
The Rust original has the 1k insert gap too: COMPARISON.md has Rust's
253-
bbtree at 36.0 ns on 1k random u64 inserts against `BTreeMap`'s 17.5, so
254-
that gap comes from the design, not the port. Of the many-map gaps,
251+
The Rust original has the 1k insert gap too: COMPARISON.md has
252+
bbtree (Rust) at 36.0 ns on 1k random u64 inserts against `BTreeMap`'s 17.5, so
253+
that gap comes from the design, not bbtree++. Of the many-map gaps,
255254
iteration was profiled: the walk read a leaf's entries with one load,
256255
whose steps the prefetcher didn't follow (since fixed; PORTING.md, [iteration](../../PORTING.md#p16-for_each-beside-iterators-for-rusts-folds)). Building them
257256
pays a full 1 KiB root page a map, where abseil sizes its root leaf to its
258257
entries (FUTURE_WORK.md). No Rust `BTreeMap` figures for the many-map
259258
cells are at hand.
260259

261260
`std::unordered_map` beats every ordered map on lookups, random inserts
262-
and upserts, as expected; not on sequential inserts, which bbtree appends
261+
and upserts, as expected; not on sequential inserts, which bbtree++ appends
263262
to its last leaf, or on 1M random removes.

0 commit comments

Comments
 (0)