docs(spec): reconcile the memory-pool spec with the as-built system#110
Merged
Conversation
The spec was the original greenfield brief and had drifted from the delivered, v1.0.0-frozen library. Reconcile sections 1-6 with the implementation and cross-link the realizing ADRs; formalize the section 2/3 subsection anchors already referenced across the ADR set; add a section 7 mapping the spec to its decision records and listing the explicitly deferred items. - 1: state the external-vs-internal fragmentation scope precisely - 2.2: disambiguate dynamic growth as non-contiguous chunk-linking with pointer-validity guarantees (ADR-0022/0023/0024) - 2.4: document the mutex/lock-free policy knob + ABA-tagged head (ADR-0020) - 4.1: add block-size/alignment/strict-aliasing constraints (ADR-0009) - 5: split C core / C++17 surface / error semantics / introspection, documenting double-free/foreign/NULL behaviour (ADR-0012/0016) and the InstrumentedPool introspection surface (ADR-0015/0025) - 6: point the benchmark at ADR-0014, note the contended scenario, extend the Valgrind criterion, add the sanitizer/CI tier - 7: spec->ADR map + deferred items (#107 pmr, #108 fuzz, #109 hardening) Mark the zh-Hans/ja spec translation rows stale in the i18n manifest (the established dance when an English source changes; re-sync follows in a separate PR). CHANGELOG Unreleased updated. Refs #105. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
5 tasks
8 tasks
danielPoloWork
added a commit
that referenced
this pull request
Jul 7, 2026
…ram tooling (#112) ## Summary Adds the **C4 component diagram** of the pool internals to the specification and records **Mermaid** as the repo's diagram tooling. This closes the last open item of the specification review (#105) — the documentation-drift scope of #105 already landed in #110. **No code or API change; no version bump** (rides the next release). ## Motivation #110 reconciled the spec with the as-built system but explicitly left the C4 diagram out, because the repo had no diagram-tooling convention (a mermaid-vs-plantuml decision was owed). This PR makes that decision (ADR-0041) and delivers the diagram, finishing #105. ## Changes - **Spec §4.2 (new)** — a C4-model *Component* diagram in Mermaid relating the public surface, the core engine (behind the Pimpl / C ABI), and the OS backing store; it makes the realized patterns (Pimpl, Strategy, Template Method, Composite, Decorator, Adapter, Iterator) and the C-ABI ↔ core ↔ OS boundaries visible at a glance. - **ADR-0041 (new)** — records Mermaid as the in-repo diagram tooling: C4 levels are drawn as Mermaid flowcharts with `subgraph` boundaries; PlantUML, checked-in SVG/PNG, and Mermaid's experimental `C4Component` DSL were considered and rejected. Indexed in `docs/adr/README.md`. - **Spec §7** — the new §4.2 is added to the spec→ADR map; the §7.1 "C4 component diagram" deferred bullet is un-deferred (now points at §4.2), and the benchmark-extension bullet gains its `#111` tracking reference. - **CHANGELOG** — one `Added` line under `[Unreleased]`. ## Design Patterns None introduced — ADR-0041 is a tooling decision, not a design-pattern adoption. (The diagram *documents* the patterns already catalogued in `docs/patterns/`.) ## Verification - [x] `python tools/consistency_lint.py` → **OK** (all invariants hold). - [x] Internal links & fragments resolve — the `#42-component-diagram-c4` anchor follows the same slug rule as the spec's existing `#53-error-semantics` reference. - [x] `markdownlint` clean by inspection (`MD013`/`MD040`/`MD033` are disabled repo-wide, so the Mermaid fence and long node labels pass). - [x] Documentation-only — no build, no C/C++ (the `src/**`-filtered CI jobs are skipped). ## Documentation Impact - [x] ADR added (ADR-0041) + index row. - [x] Spec updated (§4.2, §7 map, §7.1 deferred list). - [x] CHANGELOG `[Unreleased]` line added. - [x] PR metadata — assignee, `documentation` label, `v1.1.3` milestone. - No README / ROADMAP / patterns change (no user-facing API or milestone change). ## i18n note The `zh-Hans` / `ja` spec rows in `docs/i18n/translation-status.md` are already `stale` (flipped by #110) and stay `stale`; the `i18n-freshness` lint exempts stale rows. Re-syncing those two spec translations is the follow-up already owed from #110 — this PR adds to that same debt rather than creating a new one. Closes #105. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
9 tasks
danielPoloWork
added a commit
that referenced
this pull request
Jul 7, 2026
…e) (#113) ## Summary Adds `it::d4np::memorypool::PoolMemoryResource`, a `std::pmr::memory_resource` Adapter that binds one `Pool` behind the runtime `std::pmr` interface — so a **single** resource can back any `std::pmr` container (via `std::pmr::polymorphic_allocator`) **without** the per-type `PoolAllocator<T>` rebind. This is the "door left open" in ADR-0018. **Header-only and purely additive** — the frozen C ABI and the existing C++ types are unchanged, so this is a SemVer **MINOR** (`v1.2.0` candidate). It opens roadmap **Milestone 9**. ## Motivation `PoolAllocator<T>` (ADR-0018) bakes the pool into a container's *type*; `std::pmr` chooses the storage policy at *run time* by handing a container a `memory_resource*`. ADR-0018 recorded the `pmr` resource as *deferred, not rejected*. Issue #107 / Milestone 9 opens it. ## Changes - **`pool_memory_resource.hpp`** — `PoolMemoryResource : public std::pmr::memory_resource`. A non-owning back-reference to a `Pool` plus a configurable upstream resource. Deterministic `(bytes, alignment)` routing (mirroring ADR-0018 §2): fitting requests come from the pool (throwing `std::bad_alloc` on exhaustion — **never** falling back, so `do_deallocate` routes deterministically); over-sized / over-aligned requests go upstream (`std::pmr::get_default_resource()` by default). `do_is_equal` by `(pool, upstream)` identity. Gated behind `PBR_MEMORY_POOL_HAS_PMR` (a `__cpp_lib_memory_resource` feature-test) so the header is a no-op where `<memory_resource>` is unavailable. - **ADR-0042** — records the decision (routing, non-owning shape, exhaustion-throws-not-falls-back, configurable upstream, availability gate) and the rejected alternatives; ADR index row added. - **Dedicated doctest** `pool_memory_resource_test` — gated like the header; proves pool routing + exhaustion + reissue, upstream routing (via `null_memory_resource`), `is_equal`, and an end-to-end `std::pmr::list` / `std::pmr::vector` / `polymorphic_allocator` round-trip. - **Spec** — §5.2 lists the type, §7 maps it to ADR-0042, §7.1 no longer defers it. - **ROADMAP** — Milestone 9 created (ADR-0037) with this as item 9.1; #109/#108/#111 listed as 9.2–9.4. - **Doxyfile** — predefines `__cpp_lib_memory_resource` so the gated class appears on the API site. - **CHANGELOG** — `[Unreleased]` *Added* entry. ## Design Patterns - **Adapter** — a second realisation of the already-catalogued Adapter (ADR-0018), bridging the pool to the runtime `std::pmr::memory_resource` interface. No new pattern is introduced. ## Verification - [x] MSVC build clean; `pool_memory_resource` doctest **5 cases / 33 assertions pass**. - [x] `clang-format` (22.x) clean; `clang-tidy` clean on the header + test (the `(bytes, alignment)` `bugprone-easily-swappable-parameters` findings are the fixed `std::pmr` override signature — suppressed with rationale). - [x] `python tools/consistency_lint.py` → **OK**. - [ ] Full toolchain matrix / ASan / UBSan / TSan — via CI (the adapter runs under the existing test matrix; no threading added). ## Documentation Impact - [x] ADR added (ADR-0042) + index row. - [x] Spec updated (§5.2, §7 map, §7.1). - [x] ROADMAP Milestone 9 created (ADR-0037). - [x] CHANGELOG `[Unreleased]` entry. - [x] PR metadata — assignee, `feat` label, `v1.2.0` milestone. - **Deferred to the `v1.2.0` release PR** (to keep this feature PR off the *translated* docs surface — editing them trips the `i18n-freshness` gate): the `README.md` Milestone-9 table row (a release-time refresh per M8.8) and the `docs/patterns/README.md` Adapter-row refinement (the Adapter pattern is already catalogued; the pmr application is fully documented in ADR-0042 and the spec §7 map). The release PR refreshes both and re-syncs the `zh-Hans` / `ja` translations in one pass. The spec rows remain `stale` (already flagged since #110/#112). Closes #107. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Closes the documentation scope of #105. The spec
(
docs/specs/01_spec_cpp_memory_pool.md) was the original greenfield brief; the library hassince shipped with the public API frozen at
v1.0.0and 40 ADRs. The spec had driftedfrom the as-built system — so most of #105's "gaps" were really spec-vs-implementation
documentation drift. This PR reconciles the spec with what was actually delivered and
cross-links every realizing ADR. No code or API change.
Section-by-section
"zero fragmentation" claim silently ignored internal fragmentation).
chunked expansion via a linked chunk list; outstanding pointers stay valid across growth
(no relocation); range validation is a multi-chunk membership test (ADR-0022/0023/0024).
NONE/MUTEX/LOCKFREE) and theABA-tagged Treiber-stack head (ADR-0020).
block_size >= sizeof(void*),alignof(std::max_align_t)guarantee, strict-aliasing-safe*static_cast<void**>access,and the intrusive-list-vs-bitmap decision (ADR-0009).
create_dynamic), C++17 surface(
Pool/TypedPool/PoolAllocator/InstrumentedPool), error semantics(double-free / foreign-pointer /
NULL, ADR-0012/0016), and introspection(ADR-0015/0025).
scenario, extends the Valgrind criterion with
definitely lost: 0 bytes, and adds theASan/UBSan/TSan + CI tier.
tracking issues.
Section-level anchors (
§1–§6,§6.1/6.2/6.3) are preserved; the§2/§3bullet lists arepromoted to the numbered subsections (
§2.1–§2.4,§3.1–§3.3) that the ADR set alreadyreferences, so those cross-references now resolve.
i18n gate
Editing a translated source trips the
i18n-freshnessconsistency-lint check in CI, so thetwo spec rows (
zh-Hans,ja) indocs/i18n/translation-status.mdare flipped tostalein this PR (the check exempts
stalerows). A follow-up PR will re-sync the translations andre-pin them to this commit — the established post-change i18n dance.
Validation
python tools/consistency_lint.py→ OK (all invariants hold).version.hppbump (rides the next release).Not in this PR (stay tracked)
the repo yet); remains in Spec review: harden and quantify the memory-pool spec (docs/specs/01_spec_cpp_memory_pool.md) #105.
std::pmradapter), test(ci): add a coverage-guided fuzzing harness for the pool surface #108 (fuzzing), feat(cpp): opt-in debug hardening — freed-block poisoning, canaries, free-list safe-linking #109 (hardening).Refs #105.