Skip to content

Commit fc74a0d

Browse files
committed
README: results up front, features, status with testing and how the port was made
1 parent 288dfd0 commit fc74a0d

1 file changed

Lines changed: 40 additions & 15 deletions

File tree

‎README.md‎

Lines changed: 40 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,20 @@
11
# bbtree++
22

3-
A C++20 port of [bbtree](https://github.com/XiangpengHao/bbtree), the B+-tree
4-
ordered map by Xiangpeng Hao: the same nodes, layouts, inline keys, prefix
5-
stripping, batches, optimistic lock coupling and file maps, in C++.
3+
bbtree++ is a C++20 port of [bbtree](https://github.com/XiangpengHao/bbtree), the B+-tree
4+
ordered map by Xiangpeng Hao originally implemented in Rust.
5+
6+
* bbtree++ outperforms the original in most cases:
7+
see [bbtree/bench/COMPARISON.md](bbtree/bench/COMPARISON.md) for details
8+
* bbtree++ outperforms the standard `std::map` in almost all cases while using less memory:
9+
see [bbtree/bench/CPP_MAPS.md](bbtree/bench/CPP_MAPS.md) for details
10+
11+
## Features
12+
13+
bbtree++ keeps the Rust original's design: its nodes and their layouts,
14+
inline keys, prefix stripping, batched operations, optimistic lock coupling
15+
and file maps.
16+
[design/](design/) holds the original's design documents, which bbtree++
17+
follows.
618

719
- `bbtree::unsync::bbtree_map` and `bbtree_set`: drop-in replacements for
820
`std::map` and `std::set`, for one thread.
@@ -12,18 +24,6 @@ stripping, batches, optimistic lock coupling and file maps, in C++.
1224
looked up where they lie.
1325
- Zero dependencies: headers only, C++20, Clang 15+ or GCC 13+; CMake 3.28+.
1426

15-
[bbtree/bench/COMPARISON.md](bbtree/bench/COMPARISON.md) compares the
16-
port's speed with the Rust original's, cell for cell: within 10% or faster
17-
on most, behind on `std::string` inserts and small `std::string` maps'
18-
builds (which `bbtree::compact_string` keys close) and 13% behind on
19-
bbtree-store's scans.
20-
[bbtree/bench/CPP_MAPS.md](bbtree/bench/CPP_MAPS.md) compares it with
21-
`absl::btree_map`, `std::map` and `std::unordered_map`.
22-
[PORTING.md](PORTING.md) says where and why the port differs from the Rust
23-
original, [FUTURE_WORK.md](FUTURE_WORK.md) what is left and what would be
24-
faster at the cost of more code, [PLAN.md](PLAN.md) how the port went, and
25-
[design/](design/) holds the original's design, which the port follows.
26-
2727
## Usage
2828

2929
### One thread
@@ -146,6 +146,31 @@ cmake --preset fuzz && cmake --build --preset fuzz # li
146146
| `bbtree-store/` | a memory-bounded store of byte strings on the shared map |
147147
| `design/` | the Rust original's design documents |
148148

149+
## Status
150+
151+
**Testing.** 245 Catch2 tests, built for the baseline and native targets,
152+
pass under Clang and GCC with warnings as errors; CI runs them again under
153+
AddressSanitizer and UBSan, and the shared map's under ThreadSanitizer.
154+
Eight libFuzzer targets check the maps and the shared map against
155+
`std::map`, the set algebra against std's algorithms, the tree's
156+
invariants after every operation, and memory safety under keys whose order
157+
lies. CI fuzzes each target for a minute, and the ordinary tests run the
158+
same harnesses on fixed inputs. Not yet ported are the Rust crate's own
159+
map and set test suites and a random test over iterators (PLAN.md).
160+
161+
**How it was ported.** bbtree++ was written by an AI coding agent, Claude
162+
Opus 5.5, with Claude Fable 5.1 as its advisor, under a human's direction.
163+
The agent ported the Rust crate milestone by milestone (PLAN.md),
164+
following the original's design documents and the rules in
165+
[AGENTS.md](AGENTS.md). The human set the goals, contributed ideas, and
166+
reviewed and steered the work. Performance work followed the original's
167+
rules: reason about the cost first, then measure, on a port of the Rust
168+
bench that runs the same benchmarks cell for cell.
169+
170+
[PORTING.md](PORTING.md) says where and why the port differs from the Rust
171+
original, [FUTURE_WORK.md](FUTURE_WORK.md) what is left and what would be
172+
faster at the cost of more code, and [PLAN.md](PLAN.md) how the port went.
173+
149174
## License
150175
151176
Copyright (c) 2026 Xiangpeng Hao (bbtree, its design and `design/`) and

0 commit comments

Comments
 (0)