Skip to content

Commit 7cfa6ac

Browse files
marius-bughiuclaude
andcommitted
docs(BTreeDictionary): state the per-node array count precisely
A leaf holds a key and a value array; only an internal node adds a child array, so "three arrays per 31 entries" overstated a fixed count. The XML remark was already corrected; this brings docs/api/collections.md in line. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent 93b8f90 commit 7cfa6ac

1 file changed

Lines changed: 1 addition & 1 deletion

File tree

docs/api/collections.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3738,7 +3738,7 @@ A **sorted dictionary backed by a B-tree**. Keys are kept in ascending `TCompare
37383738

37393739
The BCL has no B-tree. `SortedDictionary<TKey, TValue>` is a red-black tree: one heap object per entry and roughly `log₂(n)` dependent pointer chasesabout 20 potential cache misses at `n = 1M` — for a single lookup. `SortedList<TKey, TValue>` is array-backed, so lookups are a clean binary search but every insert in the middle memmoves the tail (`O(n)`). `OrderedDictionary<TKey, TValue>` (.NET 9) is *insertion*-ordered and does not close the gap at all.
37403740

3741-
With a fan-out of 32, the same million entries sit about **4 node visits** deep, the keys inside a node are one or two cache lines the prefetcher handles well, and allocation drops from one object per entry to three arrays per 31 entries. The documented BCL-beating workload is a large ordered map under an **interleaved insert + lookup + in-order range-scan** loadtime-series keyed by timestamp, order books, LSM-style memtables. See the [BTreeDictionary benchmark](https://marius-bughiu.github.io/Celerity/dev/bench/?collection=BTreeDictionary) on the dashboard.
3741+
With a fan-out of 32, the same million entries sit about **4 node visits** deep, the keys inside a node are one or two cache lines the prefetcher handles well, and allocation drops from one object per entry to one node per 31 entries (a leaf holds a key and a value array; an internal node adds a child array). The documented BCL-beating workload is a large ordered map under an **interleaved insert + lookup + in-order range-scan** loadtime-series keyed by timestamp, order books, LSM-style memtables. See the [BTreeDictionary benchmark](https://marius-bughiu.github.io/Celerity/dev/bench/?collection=BTreeDictionary) on the dashboard.
37423742

37433743
Where it does **not** win: small maps (at a thousand entries the red-black tree is competitive, and a `SortedList` of a few dozen entries is hard to beat); a **delete-dominated** load, where rebalancing by borrow/merge measures a few percent behind `SortedDictionary`'s rotations; and any workload that never needs ordera hash table answers those in `O(1)`, so reach for `CelerityDictionary` instead.
37443744

0 commit comments

Comments
 (0)