Skip to content

Add bounded HAMT node map mutations - #491

Draft
helly25 wants to merge 9 commits into
implement/hamt-node-setfrom
implement/hamt-node-map
Draft

helly25 wants to merge 9 commits into
implement/hamt-node-setfrom
implement/hamt-node-map

Conversation

@helly25

@helly25 helly25 commented Sep 17, 2026

Copy link
Copy Markdown
Collaborator

Add the general address-stable HAMT map surface over the shared node machinery. Persistent snapshots share immutable keys and topology, while transient edits detach shared mapped payloads before exposing mutation.

AG;DR

  • Add HamtNodeMap<Key, Mapped, Hash, Equal, Options, Source> with persistent insertion and erasure plus a move-only transient editor.
  • Keep keys const and store entries in separately owned payloads so surviving entries retain stable addresses across structural mutation.
  • Detach shared payloads before mutable at, find, or iteration exposes mapped values; unchanged snapshots remain logically independent.
  • Support heterogeneous lookup, full-hash collisions, fragment widths from four through seven bits, bounded sources, maximum-size limits, and recoverable allocation failure.
  • Support nothrow move-only mapped values for persistent insertion without multiplying the core HAMT routing implementation.
  • Clone topology and payloads transactionally into alternate source domains, preserving the input on failed consuming clones.
  • Reject shared-node reference-count overflow instead of allowing ownership counts to wrap.
  • Exercise persistent and transient mutation when shared topology or payload allocation is exhausted, preserving every published value.
  • Centralize required-access null checks so persistent and transient at retain the same terminating contract without duplicate invariant branches.
  • Consolidate invariant-only mutable iterator extraction so recoverable allocation failures remain explicit without duplicating impossible error branches.
  • Keep public fallible factories consistent with STL-style container naming through try_create.
  • Document iterator/reference lifetime, nothrow constraints, synchronization, source-domain behavior, and the current whole-tree mutable-preparation tradeoff.
  • Test persistence, transient mutation, collisions, address stability, move-only values, allocation rollback, child-empty erasure, cloning, size limits, heterogeneous lookup, and all supported fragment widths.

Validation:

  • bazel --output_user_root=/private/tmp/mbo-bazel-node-map test --disk_cache=/private/tmp/mbo-bazel-disk-cache //...
  • Focused native-Clang LCOV analysis covers every recoverable path; the remaining paths are hard-failure contracts for system allocation or invalid required access.
  • Focused pre-commit checks for this edge, with local clang-tidy skipped because CI owns clang-tidy validation.
  • Focused public map/set suites pass after the try_create rename.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant