Skip to content

Add persistent HAMT entry replacement - #472

Draft
helly25 wants to merge 8 commits into
implement/hamt-clonefrom
implement/hamt-replace
Draft

helly25 wants to merge 8 commits into
implement/hamt-clonefrom
implement/hamt-replace

Conversation

@helly25

@helly25 helly25 commented Sep 15, 2026

Copy link
Copy Markdown
Collaborator

Add persistent replacement of a general HAMT entry without modifying the
original snapshot. Callers can update a stored value while preserving shared
sibling branches and recover cleanly when the block source is exhausted.

AG;DR

  • Draft implementation step based on Add independent HAMT tree cloning with bounded rollback #471 (implement/hamt-clone). Keep the
    implementation stack unmerged; this is not approval to merge a green draft.
  • TryReplaceHamtEntry borrows the original root and returns an optional owning
    root/changed result. Null roots and missing keys succeed unchanged without
    allocation; a non-null unchanged root is retained for the returned owner.
  • Found entries are copied along their routing path, including terminal
    collisions. Unchanged siblings remain shared. The replacement must preserve
    the original key and full routing hash; this is an internal precondition,
    not a public API for changing keys in place.
  • Entry copying and lookup callbacks must be nothrow. The block source must
    outlive returned nodes; each successful owning root needs a matching release
    through that source. The supplied source must be the original tree's block
    source: retained siblings are not migrated into a different allocation domain.
    Use independent cloning for cross-source migration. Existing immutable-tree
    lifetime contracts still apply.
  • Replacement can alias the original entry: values are copied before the
    original snapshot could be released. Child-copy or parent-copy exhaustion
    releases partial results and leaves original values and ownership unchanged.
  • Tests cover empty/missing lookup, deep terminal collisions, direct replacement,
    aliasing, child-copy failure, and cleanup after a child copy succeeds but its
    parent allocation fails. The fixture preserves GoogleTest's protected
    TearDown visibility and marks its stateless lookup helper static. Uses
    C++20-compatible code.
  • The published head a233cfc06 contains Add independent HAMT tree cloning with bounded rollback #471's fully green head. Post-push
    validation passes bazel test //... (165 passed, one intentionally skipped),
    focused macOS Clang ASAN/UBSAN, focused Clang coverage, and focused repository
    checks. Coverage uses the repository's macOS system-linker configuration because
    the hermetic ld64.lld cannot parse the current SDK's arm64e.x1 TAPI records.
    This PR's own CI must pass before advancing its child; ancestor checks do not
    substitute for this PR's checks.
  • No coverage scope/exclusion changes, baseline reductions, or performance
    claims. Final measurements/charts follow completion of implementation and
    own-context validation. Initial host decisions are provisional; AMD Zen 5
    remains explicitly later follow-up.

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