Skip to content

Nothrow: Substitutes for standard C++ containers and memory resources, with pluggable pointer storage policies#272

Open
MichaelSteffens17 wants to merge 49 commits into
eclipse-score:mainfrom
MichaelSteffens17:main
Open

Nothrow: Substitutes for standard C++ containers and memory resources, with pluggable pointer storage policies#272
MichaelSteffens17 wants to merge 49 commits into
eclipse-score:mainfrom
MichaelSteffens17:main

Conversation

@MichaelSteffens17

@MichaelSteffens17 MichaelSteffens17 commented Jun 15, 2026 •
edited by 4og
Loading

Copy link
Copy Markdown
Contributor

Part of #167

MichaelSteffens17 and others added 30 commits June 1, 2026 10:47
@MichaelSteffens17
Add score::shm prototype and example.
fa9e3c5
@MichaelSteffens17
Add score::shm::map.
8fab6ec
@MichaelSteffens17
Add map benchmarks.
58772db
@MichaelSteffens17
Adapt naming of vector benchmarks.
71f9ce2
@MichaelSteffens17
Updated BENCHMARK.md.
d2eca51
@MichaelSteffens17
Fixed: Emplace true in-place construction and clear() no freed-pointe…
35c54a5 
…r comparisons.

  1. Emplace — true in-place construction

   - Added a Node(parent, std::in_place_t, Args&&...) constructor and AllocateNode. Emplace to construct the value_type directly in allocated node memory
   - Emplace now allocates the node first, constructs in-place, then searches the tree; destroys the node if a duplicate key is found
   - Eliminates the intermediate stack temporary + move that the old implementation used

  2. clear() — no freed-pointer comparisons

   - Replaced the previous-tracking traversal (which compared freed addresses — UB per [basic.stc]/4) with a descend-to-leaf approach
   - Each iteration descends left/right until hitting a leaf, nulls the parent's link, then destroys the leaf and backs up to the parent
   - All pointer comparisons are against live objects only
@MichaelSteffens17
Introduce PointerPolicy to inject raw versus relocatbale behavior int…
9f0a362 
…o container algorithm without UB. Add combined benchmark.
@MichaelSteffens17
Adjust NullableOffsetPtr to nullable_ptr.
008b49c
@MichaelSteffens17
Use explicit DirectPtr for corresponding tests/benchmarks.
ca7db65
@MichaelSteffens17
Extend example to maps.
cb375fd
@MichaelSteffens17
Optimized score/shm/map.h hot paths.
b9f60a2 
- Shared insert-position search (FindInsertPosition)
- Consolidated key comparison (CompareKey) used in insert/find
- Added specialized 2-arg Emplace(...) overloads to avoid pre-construct-and-destroy on duplicates
- RebalanceFrom(..., stop_on_stable_height) early-exit for insert flows
@MichaelSteffens17
Ported std-like lookup into score/shm/map.h: lower_bound-style walk +…
428243c 
… final equality check, and reused that for insert-position search (removing extra compare/branch work). I also added a std::greater<int> regression test in score/shm/map_test.cpp.
@MichaelSteffens17
Hint-aware insertion/emplace (Insert(hint, ...), Emplace(hint, ...), …
dd6826b 
…plus OrAbort variants), with std-like neighbor checks and fallback.

Sorted fast path via maintained leftmost_/rightmost_ and boundary-aware insertion checks, used in Create(range) and Clone() with rolling hint.
Udated score/shm/BENCHMARK.md with the full latest suite results from the current codebase.
@MichaelSteffens17
Add missing std::map-compatible APIs. Rename score::shm to score::not…
778d47f 
…hrow with pointer box renames.

Move score/shm/ to score/nothrow/ to reflect that these containers and
memory resources are nothrow std-container substitutes, not
shared-memory-specific.

Rename pointer storage types to reflect their role as encoding boxes:
- OffsetPtr -> OffsetBox
- NullableOffsetPtr -> NullableOffsetBox
- DirectPtr -> RawBox (serves as both Ptr and NullablePtr)
- ShmPointerPolicy -> OffsetBoxPolicy
- ShmDirectPointerPolicy -> RawBoxPolicy
- offset_ptr.h -> pointer_box.h

Update all include paths, header guards, namespaces, BUILD targets,
documentation, and example code.

Add reverse iterators (rbegin/rend/crbegin/crend), ordered lookup
methods (count, lower_bound, upper_bound, equal_range), iterator-based
erase overloads (const_iterator and range), and equality operators.

Fix GetOrInsertDefault to use Emplace instead of constructing an
intermediate value_type, avoiding an unnecessary key copy.

All new members follow the naming conventions from score/shm/README.md:
non-allocating operations use standard snake_case spelling.
@MichaelSteffens17
Add Doxygen headers. Abort on Vector::Insert out of bounds.
6a9ff9d
@MichaelSteffens17
Improved test coverage. Suppress core dumps in EXPECT_DEATH tests.
62f6563
@MichaelSteffens17
Correctly specify the fancy pointer design analysis BENCHMARK.md
db38927 
Updated the benchmark analysis section to clarify the overhead cause and corrected terminology from 'OffsetBox' to 'OffsetPtr'.

Signed-off-by: MichaelSteffens17 <michael.steffens@vector.com>
@MichaelSteffens17
Conlation of concerns is caused by the fancy pointer design, not by O…
79d19da 
…ffsetBox.

Signed-off-by: MichaelSteffens17 <michael.steffens@vector.com>
@MichaelSteffens17
Rename benchmark from OffsetBox to OffsetBox vs OffsetPtr
67fc217 
Signed-off-by: MichaelSteffens17 <michael.steffens@vector.com>
@MichaelSteffens17
Update BENCHMARK.md
473455a 
Signed-off-by: MichaelSteffens17 <michael.steffens@vector.com>
@MichaelSteffens17
Fix typo in BENCHMARK.md regarding OffsetPtr
a3f03da 
Signed-off-by: MichaelSteffens17 <michael.steffens@vector.com>
@MichaelSteffens17
Fixed test pertubation by delegation resource, which contributed unfa…
69f845e 
…irly to NoBoundsCheck timings. Add boost::interprocess container and completed score::memory::shared::Map benchmarks.
@MichaelSteffens17
Put benchmarks and results into consistent order.
79ec896
@MichaelSteffens17
Improve nothrow map coverage
94801ba 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@MichaelSteffens17
Finish nothrow map coverage
92e7b16 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@MichaelSteffens17
Expand nothrow vector coverage
8790eeb 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@MichaelSteffens17
Complete nothrow vector coverage
23fb56c 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@MichaelSteffens17
Refine nothrow memory resource API
24d872d 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@MichaelSteffens17
More explicit about the need for robust error handling in non-excepti…
404adad 
…on contexts.
@MichaelSteffens17
More precise about API scope.
6671669
@MichaelSteffens17

MichaelSteffens17 commented Jun 17, 2026 via email

Copy link
Copy Markdown
Contributor Author

@MichaelSteffens17 @claude
Add Map::CreateWithBuffer with internal free-list pool
02ec60f 
Provision a Map's node storage directly from an external buffer, bypassing
the templated allocator the same way Vector::CreateWithBuffer does. The map
manages an internal free-list pool over the buffer: nodes are carved on
insert and recycled on erase, bounding the map to a fixed node count.

All pool state is position-independent -- the cell base is stored through the
pointer policy (offset-encoded by default) and the free-list head/capacity are
indices -- so a buffer-backed map with OffsetSlotPolicy is relocatable and can
be both read and mutated across processes mapping the same segment, without the
vtable, raw buffer pointer, and process-local upstream singleton that a
polymorphic MemoryResource would drag along.

- map.h: PoolCell union + CreateWithBuffer(), uses_buffer(), cell_size(),
  cell_alignment(), required_bytes(); pool-routed AllocateNode/DestroyNode;
  move ctor/assignment extended to carry pool state.
- map_test.cpp: tests for empty/insert/find, capacity bound, freed-cell reuse,
  move, and OrAbort-on-exhaustion death test.
- bounded_containers.h: convert the shared-memory example bundle to the
  allocator-free buffer API.
- README.md: document the cross-process map mutation capability.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
MichaelSteffens17 and others added 3 commits June 25, 2026 17:30
@MichaelSteffens17 @claude
example: demonstrate cross-process map insertion
e73af55 
The child now inserts new keys into the parent's map, exercising node
allocation from the shared free-list pool across processes (not just in-place
value updates). The parent observes the grown map (size 3 -> 5) after remapping
the segment, confirming pooled allocation is position-independent.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@MichaelSteffens17 @claude
Abort on misaligned buffer in Map::CreateWithBuffer
5ea6c9a 
A buffer not aligned to cell_alignment() would misalign the pooled nodes.
That is a caller precondition violation, so trap it with std::abort() like the
map's other contract checks rather than returning an error. Add a death test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@MichaelSteffens17 @claude
example: document cross-process map insertion in README
74f241d 
Reflect the child's new insertion step: the README now describes node
allocation from the shared free-list pool across processes (map grows 3 -> 5),
not just in-place value updates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
MichaelSteffens17 and others added 7 commits July 13, 2026 09:52
@MichaelSteffens17 @claude
docs: move failure handling model to its own architecture document
85ab5ad 
The error/violation categorization was defined only inside the component
request, a proposal-stage document. Give it a durable home as a dedicated
architecture document (doc__nothrow_failure_handling, realizes
wp__component_arch) so requirements, README, and the CR can reference one
normative definition instead of duplicating it:

- architecture/failure_handling.rst: full model -- category definitions, the
  API-choice rule, and the out-of-scope rationale for process termination.
- architecture/index.rst: reference the model from Design Principles and add
  the toctree entry.
- index.rst (CR): condense the section to a summary plus a :need: reference.
- score/nothrow/README.md: cross-reference the model so code-side readers
  find the defined terms behind the API conventions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@MichaelSteffens17 @claude
docs: reference the failure handling model from the nothrow comp_reqs
3c475c7 
The four requirements that encode the failure categories now state which
category they realize and link doc__nothrow_failure_handling: alloc_fail,
create, and mutate_result realize the error category; or_abort realizes the
violation category. pointer_policy and asil are unrelated and unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@MichaelSteffens17 @claude
docs: make the need/budget separation the headline argument of the model
ddda0af 
The architectural motivation for error-as-default was buried inside the
out-of-scope termination subsection. Restructure failure_handling.rst:

- New section "Memory need and memory budget are separated": budget is sized
  by configuration at integration time while need arises at run time; input
  validation at trust boundaries happens in a different component than the
  allocation; resources are shared to limit config parameters, coupling
  consumers; consumption logic evolves independently in reusable parts. The
  resulting asymmetry -- practically impossible to prove sizing correct by
  testing, easy for an attacker to trigger exhaustion -- is why allocation
  failure is a reachable runtime condition (error) by default. The per-request
  recovery example moves here as the payoff.
- "Choosing between the two APIs" now closes with the co-located-budget
  criterion: only where the separations are deliberately eliminated is a
  violation classification legitimate.
- "Out of scope: process-level termination" shrinks to a pure scope statement.
- CR: summary names the need/budget separation; Security Impact cites the
  model for the DoS argument instead of restating it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@MichaelSteffens17 @claude
docs: add Tony-table comparison with standard containers
a19d5e1 
Side-by-side comparison in the C++ standardization-paper style, requested in
the component review (issue eclipse-score#167 sync). Eight scenarios, each mapped onto the
failure handling model, with the standard-container cell degrading from
fragile (masked capacity defects, pseudo-recoverable at()) through terminating
(construction, growth, attacker-sized input) to inexpressible (pre-flight
budget check, failure-path testing, shared-memory placement).

Ground rules keep it honest: the standard cell always shows the strongest
available attempt (std::pmr, reserve-first, boost::interprocess for SHM), and
every row states the no-exceptions environment assumption.

Scoped explicitly as an input to the planned "when to use which container"
guideline, not the guideline itself -- that must additionally weigh the
pointer-slot policy choice and third-party interop.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@MichaelSteffens17 @claude
docs: add nothrow usage guidelines; scope claims as deployment constr…
14052c9 
…aints

Add the "when to use which container" guideline requested in the component
review (doc__nothrow_usage_guidelines), covering both decisions:

- Container choice: standard by default where its failure semantics are
  acceptable; score::nothrow when allocation failure must be a contained,
  testable error, the process must survive memory pressure, a budget contract
  should trap at the defect site, or state is placed in shared memory. Within
  nothrow, Result APIs by default, OrAbort only for co-located budgets.
- Pointer policy: OffsetSlotPolicy by default -- one generic container type
  passed by reference serves both shared-memory IPC and process-local buffers
  (e.g. socket-backed) without adapting application code to the transport,
  at measured ~1-14% worst-case overhead (BENCHMARK.md), far below the
  alternatives (type duplication, erasure, barrier-based fancy pointers).
  RawSlotPolicy only for closed single-address-space subsystems with a
  profiled hot path, accepting the type fork it causes.
- Decision summary table as quick reference.

Also reword the "not general-purpose replacements" claim in the comparison
document and the guideline: it stated an organizational rollout constraint
(std required at third-party boundaries, targeted adoption) as if it were a
property of the types, which our own failure analysis contradicts. The claims
now describe where the types can be deployed today, not their generality.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@MichaelSteffens17 @claude
docs: delimit component scope relative to communication modelling in …
5e69adb 
…the CR

Clarifies the scope questions raised in the issue eclipse-score#167 allocator meeting
(2026-06-25) and discharges its TODO to document usage examples in the
component request. New CR section "Scope and Relation to Communication
Modelling", placed after Rationale:

- nothrow types are library types linked into an executable, not a platform
  service or communication stack.
- The only interprocess contract is the binary representation of container
  state in shared memory (standard layout, offset pointer slots, bounded
  objects with dynamic content). PMR memory management does not cross that
  boundary; provisioning stays with the memory-aware side (CreateWithBuffer),
  the allocator being type-compatibility decoration in that scenario.
- Two separable aspects: stable binary representation (ABI) and API (error
  propagation, provisioning hidden behind a generic allocator, IPC-unaware
  interfaces without payload copying or rebuilds).
- No relation to communication modelling (AUTOSAR-AP style): score's decision
  not to model executables/components is neither changed nor depended on. The
  types can appear as elements in generator output of such a model, and work
  equally in pure API-driven configurations.
- Usage scenarios from the review: event (sender-owned pool, one-to-many),
  method (one-to-one, ownership passing intra-process incl. C++/Rust via
  opaque resource references), gateway serialization (SOME/IP).

Architecture overview gets a one-line pointer to the CR scope section.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@MichaelSteffens17 @claude
example: demonstrate co-located vs dislocated memory budgets
04e99eb 
Add resource_scopes.cpp, the failure-handling decision rule in runnable form
and the executable companion to the API aspect of the CR scope section (the
SHM demo covers the binary-representation aspect):

- Co-located budget: local buffer + MonotonicBufferResource in the consuming
  scope, populated with OrAbort -- failure could only be a bug and traps at
  the defect site.
- Dislocated budget: main() sizes the process-wide default resource centrally
  (standing in for integration-time configuration); business logic returns
  score::Result, an oversized request is rejected as a contained error, and
  the process keeps serving. Also demonstrates SetDefaultResource, previously
  unexercised outside tests.

Reference the runnable examples from the CR (scope section and How to Teach
This), the usage guidelines, and example/README.md, discharging the review
TODO to document usage examples in the component request.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@MichaelSteffens17 MichaelSteffens17 mentioned this pull request Jul 13, 2026
Open
10 tasks
@MichaelSteffens17 @claude
docs: comparison scope note -- main focus, not "only" failure semantics
3b00192 
Scenario 8 (shared-memory placement) contradicted the "failure semantics
only" claim. The note now states failure semantics as the main focus and
scopes scenario 8: the pointer-slot policy affects container construction and
cross-process synchronization, but not API use or failure robustness.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@limdor limdor limdor left review comments
@antonkri antonkri Awaiting requested review from antonkri antonkri is a code owner
@4og 4og Awaiting requested review from 4og 4og is a code owner
@pawelrutkaq pawelrutkaq Awaiting requested review from pawelrutkaq pawelrutkaq is a code owner
@arkjedrz arkjedrz Awaiting requested review from arkjedrz arkjedrz is a code owner
@aschemmel-tech aschemmel-tech Awaiting requested review from aschemmel-tech aschemmel-tech is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

@MichaelSteffens17 MichaelSteffens17

Labels

None yet

Projects

BAS - Baselibs FT
Status: In Progress

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@MichaelSteffens17 @limdor