A header-only C++20 library for containers, concurrency, numerical computing, serialization, and diagnostics. Core utilities have no mandatory third-party dependencies; optional platform backends and benchmark competitors have separate requirements.
⚠️ Work in progress — APIs are not yet stable.
All CI Workflows
FAT-P provides independently includable utilities in the fat_p namespace.
Public headers live in include/fat_p/; component tests,
benchmarks, and manuals live in components/. Copy the entire
header directory, including its nested implementation directories, or use the
fatp CMake interface target.
FAT-P is developed through human–AI collaboration. Matthew Schroeder
provides direction, constraints, judgment, and architectural contributions,
including the introduction of BoneId and related design work. AI systems —
primarily Claude (Anthropic), with contributions from ChatGPT, Gemini, and Grok —
contribute architecture, implementation, tests, documentation, and governance.
Vendored code in ThirdParty/ retains its upstream authorship and
licenses.
The library was developed using independent design, cross-review, synthesis, focused verification, and context reset cycles. Current contributor and assistant instructions start at guidelines/README.md. Fat-P AI-Collaborative Development Methodology preserves the historical process; Authors.md records attribution.
This is a prerelease project. APIs may change, and passing a particular workflow
does not establish production readiness. See the live workflow links above and
current verification record for checked
configurations and known limits. Benchmark reports in
benchmark_results/ describe measurements from their
recorded source revisions, machines, and workloads.
- A compiler and standard library supporting C++20.
- CMake 3.21 or newer for the CMake instructions below.
- x64 when using the MSVC CMake build; 32-bit MSVC is explicitly rejected.
The core CI workflow defines the current
matrix: GCC 12/13 with C++20 and GCC 14 with C++23, Clang 16 with C++20 and
Clang 17 with C++23, and hosted MSVC with C++20 and /std:c++latest. Individual
component workflows may cover additional configurations.
Some facilities select platform-specific backends. For example,
NumaAllocator uses libnuma on Linux when
available, and Stacktrace selects a standard-library,
libunwind, POSIX, Windows, or stub backend. Check the selected component's
requirements and link libraries when using these facilities.
cp -r include/fat_p /your/project/include/Enable C++20 and configure both header search paths. For GCC or Clang's GNU
driver, use -I /your/project/include -iquote /your/project/include/fat_p.
For MSVC, use /I /your/project/include /I /your/project/include/fat_p.
The short-header path is also needed by nested implementation headers. Copy the
complete directory; the CMake target below configures these paths for you.
Or add FAT-P to an existing CMake project after defining your_target. Disable
the repository's test and benchmark targets when consuming only the library:
set(FATP_BUILD_TESTS OFF CACHE BOOL "Build FAT-P tests" FORCE)
set(FATP_BUILD_BENCHMARKS OFF CACHE BOOL "Build FAT-P benchmarks" FORCE)
add_subdirectory(path/to/FatP)
target_link_libraries(your_target PRIVATE fatp)Both build options default to ON in the repository's top-level CMake file.
If VCPKG_ROOT is set, that file automatically selects its vcpkg toolchain.
For the dependency-free core/test builds shown here, unset VCPKG_ROOT before
configuring; vcpkg users should supply their own valid toolchain/manifest setup.
Use namespaced includes such as <fat_p/Tensor.h>, or quoted short includes
such as "Tensor.h". On Windows with GCC or Clang's GNU driver, CMake keeps the
short-header directory out of the normal -I search path so Signal.h cannot
shadow the C library's <signal.h>. Include the signal component as
"Signal.h" or <fat_p/Signal.h>.
Per-component tests, benchmarks, and user manuals live under components/. Highlights by area:
| Component | Description |
|---|---|
| SmallVector | Vector with inline element storage and heap growth |
| FlatMap / FlatSet | Sorted vector-backed associative containers |
FastHashMap (FatPHashMap) |
Open-addressing hash map with policy variants |
| StableHashMap | Hash map with pointer/reference stability on insert |
| CircularBuffer | Fixed-capacity ring buffer with O(1) push/pop |
| IntrusiveList | Non-owning intrusive doubly linked list with no node allocations |
| SlotMap | Generational index container with stable handles |
| SparseSet | Sparse set with dense iteration |
| BitSet | Fixed-size bit set with compiler intrinsics |
| PolicyIterator | Policy-based iterator utilities for container traversal |
| Component | Description |
|---|---|
| ObjectPool | Object pool with concurrency policy support |
| AllocationStrategies | Lightweight allocator policies |
| NumaAllocator | NUMA-aware memory allocator (Linux CI) |
| StringPool | String interning with policy-based thread safety |
| AlignedVector | Cache-aligned vector for HPC workloads |
| HpcVector | Aligned vector with NUMA allocation policies and aligned fallback when NUMA is unavailable |
| Component | Description |
|---|---|
| ThreadPool | Work-stealing thread pool with priority queues |
| WorkQueue | Bounded sharded MPMC work queue with relaxed global ordering |
| LockFreeQueue | Lock-free MPMC queue with ABA prevention |
| LockFreeRingBuffer | Lock-free ring buffers (SPSC and MPMC) |
| ConcurrencyPolicies | Thread-safety policy classes for containers |
| RateLimiter | Token bucket, leaky bucket, and sliding window rate limiters |
| Signal | Signal/slot implementation |
LockFreeQueue, both LockFreeRingBuffer variants, and WorkQueue require
trivially copyable element types. Their component manuals describe ordering and
threading contracts.
| Component | Description |
|---|---|
| Expected | Monadic error handling (value-or-error type) |
| Enforce | Design-by-contract macros with customizable predicates |
| DiagnosticContext | Thread-local context stack for richer contract failures |
| ScopeGuard / ScopeGuardExpected | Policy-based RAII cleanup and Expected-aware guards |
| ContractException | Exception classes for contract violations |
| CheckedArithmetic | Overflow-safe arithmetic for integers and floats |
| EnforcedInit | Wrapper enforcing explicit initialization |
| EnhancedBoundsChecking | Bounds-checking helpers beyond raw indexing |
| Component | Description |
|---|---|
| JsonLite / JsonStreamLite | Standalone JSON (variant model, struct macros, ADL dispatch) |
| FatPJson / FatPJsonStream | Expected-based JSON bridge over JsonLite |
| XmlLite | Standalone XML parser/serializer with struct macros and vector modes |
| CborLite / CborStreamLite | Low-level CBOR encoder/decoder and streaming parser |
| FatPCbor / FatPCborStream | Expected-based CBOR bridge |
| BinaryLite / FatPBinary | Binary serialization (lite and Fat-P integrated) |
| Component | Description |
|---|---|
| Tensor / TensorView / TensorLayout / TensorDType | Owners, signed-stride views, layouts, and scalar metadata |
| TensorAlgorithms | Serial owner/view arithmetic, broadcasting, transforms, equality, and hashing |
| TensorSlice / TensorReductions | Python-style metadata slicing and deterministic checked axis reductions |
| TensorInterop / TensorMatmul | Span/descriptor/fixed-size bridges and native matmul, dot, outer, diagonal, and trace |
| TensorExecution | Opt-in caller-owned contexts; serial defaults and deterministic matmul/tensorDot output scheduling |
| TensorContractions | Explicit-axis tensorDot; ordered checked folds over owners and strided views |
| TensorSelection | Stack, concatenate, take, take-along-axis, and gather-ND algorithms |
| TensorStatic | Fixed-size stack/constexpr tensor math |
| TensorRanked | Fixed-rank, runtime-extents tensor owners and views |
| TensorEquality | Policy-based tensor equality integration |
| CSRMatrix | Compressed Sparse Row matrix with parallel/HPC variants |
| SimdVector | Universal SIMD wrapper for vectorized operations |
| FloatingPointComparison | ULP, relative, and absolute float comparison |
| Jet | Fixed-size forward-mode automatic differentiation scalar |
| Component | Description |
|---|---|
| Skeleton / OwnerSkeleton | Non-owning and owning hierarchical item registries with Bone addresses |
| CapabilityRegistry / SkeletonSerializer | Capability-name registration and binary stream helpers for Skeleton items |
| StateMachine | Type-safe FSM with compile-time transition validation |
| Component | Description |
|---|---|
| DiagnosticLogger | Structured logging with JSON output and scope tracking |
| Stacktrace | Stack trace capture with platform backends and a stub fallback |
| Reflection | Compile-time reflection with unified macro syntax |
| EnumPlus | Enhanced enums with string conversion and iteration |
| StrongId | Type-safe ID wrapper preventing cross-domain mixing |
| FeatureManager | Runtime feature flags with compile-time optimization |
| ServiceLocator | Policy-based service locator with scoped overrides |
| IdGenerator | Type-safe unique ID generation with recycling |
| Stringify | Type-to-string conversion using C++20 concepts |
| EqualityAny / EqualityComparisons | Type-erased and typed equality helpers |
| DebugOnly | Debug-only utilities that compile away in release |
| ConstexprUtilities | Compile-time utility functions |
| Concepts / FatPConcepts | C++20 concepts for type constraints |
| PlatformDetection / CppFeatureDetection | Compiler, OS, architecture, and feature detection |
| CacheUtilities | Cache control and prefetching utilities |
| ValueGuard | Temporary value modification with automatic restoration |
| ViewLifetimeTracking | Debug-only lifetime tracking for views and references |
| MemoryMappedFile | Cross-platform memory-mapped file I/O (Linux CI) |
| SlidingFileWindow | Sliding window access to large files (Linux CI) |
| CoroutineTask / ExpectedAsyncTask | Coroutine tasks and future-backed Expected tasks |
| Factory | Policy-based factory with compile-time customization |
| Component | Description |
|---|---|
| FatPTest | Zero-dependency test framework |
| FatPBenchmarkRunner | Zero-dependency benchmark infrastructure |
Browse the headers, components, and
workflows for the current inventory. CMake discovers
component test and benchmark sources through
cmake/FatPComponents.cmake.
FatP/
├── include/fat_p/ # Library headers
├── components/ # Per-component tests, benchmarks, and docs
├── ThirdParty/ # Vendored headers used by tests and benchmarks
├── benchmark_results/ # Published competitive benchmark analysis
├── Teaching/ # Guides, case studies, and reference material
├── guidelines/ # Canonical contributor guidelines and project profile
├── documents/ # Historical development methodology
├── postmortems/ # Incident analyses and conversation records
├── cmake/ # Component target discovery and configuration
├── tools/ # Build scripts, CI generators, Desktop sync (see tools/README.md)
└── .github/workflows/ # Correctness, benchmark, tooling, and maintenance workflows
cmake -S . -B build -DFATP_BUILD_TESTS=ON -DFATP_BUILD_BENCHMARKS=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 2
ctest --test-dir build -C Release --output-on-failureUse a configured compiler environment; on Windows with MSVC, use an x64 developer shell or select an x64 generator. CMake registers component tests as individual executables; the separate GitHub core workflow builds its aggregate runner. Check current verification for the latest recorded results and limitations.
Benchmark sources live in each component's benchmarks/ directory, alongside
its tests/ and docs/ directories where present. Build them separately from
the correctness suite:
cmake -S . -B build-bench -DFATP_BUILD_TESTS=OFF -DFATP_BUILD_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build-bench --config Release --target benchmark_SlotMap --parallel 2Competitor availability depends on installed libraries, vendored headers, and
the selected platform. For hosted runs, the
dependency builder prepares shared
caches; component benchmark workflows restore them. The
all-component dispatcher builds the
caches before starting those workflows. Reports and raw historical logs are in
benchmark_results/; component-specific measurements also
live under components/<Component>/results/ where present.
Start with component user manuals under components/ for API
contracts, Teaching/ for explanatory material, and
CONTRIBUTING.md for the contribution process.
Build helpers, component CI generators, and optional Desktop synchronization
tools live under tools/. Regenerate the marked README workflow badge
block with python tools/update_readme_badges.py after adding or removing
workflows. This generator lists the workflow files actually present; component
workflow generation and benchmark workflow maintenance are separate tasks.
See tools/README.md and
the contributor guidelines for the applicable procedures.
MIT — see LICENSE.