Skip to content

docs(spec): add a C4 component diagram and record Mermaid as the diagram tooling#112

Merged
danielPoloWork merged 1 commit into
masterfrom
docs/c4-component-diagram
Jul 7, 2026
Merged

docs(spec): add a C4 component diagram and record Mermaid as the diagram tooling#112
danielPoloWork merged 1 commit into
masterfrom
docs/c4-component-diagram

Conversation

@danielPoloWork

@danielPoloWork danielPoloWork commented Jul 7, 2026

Copy link
Copy Markdown
Owner

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

  • python tools/consistency_lint.py → OK (all invariants hold).
  • Internal links & fragments resolve — the #42-component-diagram-c4 anchor follows the
    same slug rule as the spec's existing #53-error-semantics reference.
  • markdownlint clean by inspection (MD013/MD040/MD033 are disabled repo-wide, so
    the Mermaid fence and long node labels pass).
  • Documentation-only — no build, no C/C++ (the src/**-filtered CI jobs are skipped).

Documentation Impact

  • ADR added (ADR-0041) + index row.
  • Spec updated (§4.2, §7 map, §7.1 deferred list).
  • CHANGELOG [Unreleased] line added.
  • 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.

@danielPoloWork @claude
docs(spec): add a C4 component diagram and record Mermaid as the diag…
d2e0236 
…ram tooling

Closes the last open item of the specification review (#105): the C4
component diagram of the pool internals. The diagram is authored in
Mermaid and embedded in spec §4.2; ADR-0041 records Mermaid as the
in-repo diagram tooling — C4 levels are drawn as flowcharts with
subgraph boundaries, and PlantUML, checked-in images, and Mermaid's
experimental C4Component DSL were considered and rejected.

Also cross-links the new §4.2 in the §7 spec→ADR map, un-defers the C4
item in §7.1 (now pointing at §4.2), and adds the #111 tracking ref to
the benchmark-extension deferred bullet.

Documentation-only; no code or API change; no version bump (rides the
next release). The zh-Hans/ja spec translation rows stay stale pending
the re-sync follow-up already owed from #110.

Refs #105

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@danielPoloWork danielPoloWork added this to the v1.1.3 milestone Jul 7, 2026
@danielPoloWork danielPoloWork added the documentation Improvements or additions to documentation label Jul 7, 2026
@danielPoloWork danielPoloWork self-assigned this Jul 7, 2026
@danielPoloWork danielPoloWork marked this pull request as ready for review July 7, 2026 18:34
@danielPoloWork danielPoloWork merged commit 8766a00 into master Jul 7, 2026
4 checks passed
@danielPoloWork danielPoloWork mentioned this pull request Jul 7, 2026
Merged
9 tasks
danielPoloWork added a commit that referenced this pull request Jul 7, 2026
@danielPoloWork @claude
feat(api): add a std::pmr::memory_resource adapter (PoolMemoryResourc…
d4afec5 
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@danielPoloWork danielPoloWork

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

v1.1.3

Development

Successfully merging this pull request may close these issues.

Spec review: harden and quantify the memory-pool spec (docs/specs/01_spec_cpp_memory_pool.md)

1 participant

@danielPoloWork