v1.0.0

pbr-cpp-memory-pool v1.0.0 — the first stable release

v1.0.0 is the stable reference release of pbr-cpp-memory-pool. The public C ABI and the C++ surface are now frozen under the SemVer 1.0 promise — no breaking change without a 2.0.0. Milestone 7 added the release polish (published API docs, an expanded README, installable packaging, and the compliance audits) on top of the feature set delivered across Milestones 0–6.

What the library is

A fixed-block-size memory pool with constant-time O(1) allocation and deallocation and zero external fragmentation, built on an implicit free list (free blocks store the next-free pointer in their own storage, so live blocks carry zero per-block metadata — spec §4). It is C++17 internally with an ANSI C (C89-compatible) public surface and no external dependencies (spec §3.3).

The public C API (spec §5)

typedef struct memory_pool memory_pool_t;

memory_pool_t* memory_pool_create(size_t block_size, size_t block_count);
void*          memory_pool_alloc(memory_pool_t* pool);
void           memory_pool_free(memory_pool_t* pool, void* block);
void           memory_pool_destroy(memory_pool_t* pool);

The C++ surface

• Pool — move-only RAII owner (ctor → create, dtor → destroy), with the dual-verb exception policy (allocate throws std::bad_alloc, try_allocate is noexcept), the Pool::make Factory Method, and the fluent PoolBuilder.
• TypedPool<T> — compile-time-correct block_size for T, with construct / destroy object-lifetime verbs.
• PoolAllocator<T> — a Cpp17Allocator Adapter so std::list / std::map / std::set and custom containers draw nodes from the pool.
• InstrumentedPool + PoolObserver — opt-in Decorator (counters, occupancy, on-demand logging) and runtime Observer (lifecycle events), zero cost to an undecorated Pool.
• FreeListView — a read-only diagnostic Iterator over the free list, compiled out of release builds unless explicitly enabled.

Capabilities delivered across Milestones 0–6

• O(1) alloc/free on the implicit free list; NULL (C) / std::bad_alloc (C++) on exhaustion (spec §2.1–§2.3).
• Optional, macro-configurable thread safety — NONE (default, single-thread fast path preserved), MUTEX, or LOCKFREE (ABA-tagged Treiber stack), a compile-time Strategy so the single-threaded build pays nothing (spec §2.4).
• Optional dynamic growth — geometric overflow chunks acquired on exhaustion (Composite chunk list), opt-in per pool (spec §2.2).
• Minimal overhead — 0 bytes per block, ≤ 192 bytes per pool, CI-gated (spec §3.2).
• Leak-free — destroy returns every byte to the OS, Valgrind-gated (spec §3.1).

Milestone 7 — what v1.0.0 adds on top

• M7.1 — Doxygen API-reference site (ADR-0027): the public-header contract is built warn-as-error on every PR and published to GitHub Pages on master.
• M7.2 — README for the v1.0 audience: a full Usage section (six compilable examples), a consolidated Performance summary, and a Compatibility matrix.
• M7.4 — Install / packaging, Phase 1 (ADR-0028): find_package(pbr_memory_pool CONFIG REQUIRED) + target_link_libraries(app pbr::memory_pool), a relocatable package config, and a pkg-config .pc. Release tarballs are now complete find_package-ready install trees.
• M7.3 / M7.5 / M7.6 — audits: the CHANGELOG v1.0.0 audit, the patterns-catalogue audit (all eleven adopted patterns have an ADR + a live code location), and the specification-compliance acceptance audit (ADR-0029).

Stability promise

From v1.0.0 the public C ABI (memory_pool_*, including the O(1) introspection accessors) and the C++ surface (Pool, TypedPool<T>, PoolAllocator<T>, InstrumentedPool, PoolObserver) are stable. Source-incompatible changes will only land in a future 2.0.0; 1.x releases are additive or fix-only. The CMake package config advertises SameMajorVersion compatibility accordingly.

Spec Coverage Map — accepted

All fifteen Spec Coverage Map rows are ✅, re-verified end-to-end in the M7.6 acceptance audit (ADR-0029) against ten CTest targets (95 doctest cases + the spec_6_2_valgrind C program), the c_consumer_min.c ANSI-C consumer, and the CI build / sanitizer / Valgrind / thread-safety / TSan / benchmark / C89-C99 / zero-dependency jobs. No gap, regression, or unsupported mark.

Architecture Decision Records

Twenty-nine ADRs (0001–0029) record every architectural decision — the free-list layout, the C/C++ boundary and exception policy, the eleven design patterns, the thread-safety and dynamic-growth strategies, the metadata budget, the documentation and packaging pipelines, and the v1.0 acceptance audit. Index: docs/adr/README.md.

Performance

Versus malloc/free on the maintainer's Skylake × MSVC × x64 reference host: a pre-sized fixed pool is 4–11× faster single-threaded, a growing pool stays ~2× faster amortized, and under contention LOCKFREE beats MUTEX. Full reports under docs/bench/; methodology in ADR-0014.

What this release does not contain (deferred, by design)

• Double-free detection (deferred from M2 / ADR-0012).
• Per-thread caches (ADR-0020 §4) and lock-free dynamic growth (ADR-0024 §2).
• Pool shrink-on-idle (ADR-0022).
• vcpkg / Conan packaging — Phase 2 distribution, post-1.0 (ROADMAP §7.8–§7.9).

None corresponds to a spec clause, so none affects the v1.0 acceptance.

Install and use

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DPBR_MEMORY_POOL_BUILD_TESTS=OFF
cmake --build build
cmake --install build --prefix /your/prefix

find_package(pbr_memory_pool CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE pbr::memory_pool)

Verifying the release

Each platform tarball produced by release.yml is a complete cmake --install tree — the full public-header set, the static archive, the CMake package config, and the pkg-config .pc — plus top-level LICENSE / README.md / CHANGELOG.md. SHA-256 checksums are in SHA256SUMS:

sha256sum --check SHA256SUMS

Links

• Changelog entry: CHANGELOG.md — [1.0.0]
• Milestone plan: ROADMAP.md — Milestone 7
• Specification: docs/specs/01_spec_cpp_memory_pool.md
• Acceptance audit: ADR-0029
• Previous release: docs/releases/v0.6.0.md