feat!: Drop returns bool, Put doesn't stack-overflow #21

Merged

mvhutz merged 12 commits from feat/safe-put into main 2026-04-17 01:31:02 +00:00

Conversation 0 Commits 12 Files Changed 6

+107 -65

mvhutz commented 2026-04-03 22:56:32 +00:00

Owner

Copy Link

Copy Source

Description

Closes #11. This PR attempts to grapple with:

1. How Table.Put is not atomic, and is non-recoverable upon ErrBadHash.
2. How Table.Drop cannot provide a meaningful error scenario.
3. How Table.Put will stack-overflow if it is unable to construct a table on resize.

Changes

1. Clearly note in the documentation that upon this error, you MUST rebuild the table from the source data.
   • Add this note to the documentation for ErrBadHash.
   • Note in the package-level documentation that Table is NOT a source of truth, and should not be trusted as one.
2. Update the contract of Table.Drop to return bool. Ignore the error when shrinking the table.
3. Limit resizes to 64.
   • Add internal defaultResizeLimit constant.

Design Decisions

• It was tempting to return the displaced entry for Table.Put, and provide this invariant: on error, the displaced entry along + the tables current contents = the inserted entry + the old table. I chose not to, because for developers, receiving this error will probably just prompt them to just propagate it, or ignore it. Both times, the displaced entry is unused, so why return it?
• Currently, the only error in Table.Drop is caused when the user tries to shrink. But, because Table.shrink is atomic, it won't break the table. Plus, because table capacity is an internal optimization, why should the user care?
• The resize limit of 64 was arbitrary, and chosen as a large enough number to not get called unless the hash is truly broken.
• We now return an error immediately if Table.Put cannot grow, due to a hash collision. The chance an even larger table size will fit the items is astronomically small, so we choose to ignore it.

Checklist

• Tests pass
• Docs updated

## Description Closes #11. This PR attempts to grapple with: 1. How `Table.Put` is not atomic, and is non-recoverable upon `ErrBadHash`. 2. How `Table.Drop` cannot provide a meaningful error scenario. 3. How `Table.Put` will stack-overflow if it is unable to construct a table on resize. ## Changes 1. Clearly note in the documentation that upon this error, you MUST rebuild the table from the source data. - Add this note to the documentation for `ErrBadHash`. - Note in the package-level documentation that `Table` is NOT a source of truth, and should not be trusted as one. 2. Update the contract of `Table.Drop` to return `bool`. Ignore the error when shrinking the table. 3. Limit resizes to 64. - Add internal `defaultResizeLimit` constant. ### Design Decisions - It was tempting to return the displaced entry for `Table.Put`, and provide this invariant: on error, the displaced entry along + the tables current contents = the inserted entry + the old table. I chose not to, because for developers, receiving this error will probably just prompt them to just propagate it, or ignore it. Both times, the displaced entry is unused, so why return it? - Currently, the only error in `Table.Drop` is caused when the user tries to shrink. But, because `Table.shrink` is atomic, it won't break the table. Plus, because table capacity is an internal optimization, why should the user care? - The resize limit of 64 was arbitrary, and chosen as a large enough number to not get called unless the hash is truly broken. - We now return an error immediately if `Table.Put` cannot grow, due to a hash collision. The chance an even larger table size will fit the items is astronomically small, so we choose to ignore it. ## Checklist - [x] Tests pass - [x] Docs updated

mvhutz added 3 commits 2026-04-03 22:56:32 +00:00

feat: new put implementation 05b633afca

feat: drop item returns bool, whether item existed afead3330a

fix: public facing key/value fields in entry ca66ccd040

mvhutz added 1 commit 2026-04-16 03:59:05 +00:00

Merge remote-tracking branch 'origin' into feat/safe-put 1f7c64366d

mvhutz added 1 commit 2026-04-16 04:00:14 +00:00

revert: forgot about b -> t 78f7d01d5f

mvhutz added 1 commit 2026-04-16 04:05:46 +00:00

feat: use bad hash sentinel error 24b646c5dc

mvhutz added 1 commit 2026-04-17 00:33:39 +00:00

fix: assertion in fuzz test incorrect 5452c02d4e

mvhutz added 1 commit 2026-04-17 01:05:51 +00:00

docs: note that the table isnt a source of truth d13adcaa49

mvhutz added 1 commit 2026-04-17 01:11:05 +00:00

revert!: old put contract 24df23218c

mvhutz added 1 commit 2026-04-17 01:12:26 +00:00

fix: tests were out of date b395d6e1f4

mvhutz added 1 commit 2026-04-17 01:15:03 +00:00

revert: Entry -> entry bc Put() doesnt use it 7b45099cea

mvhutz changed title from WIP: feat!: put fails gracefully, allows recovery to feat!: `Table.Drop` returns `bool`, `Table.Put` doesn't cause stack-overflow 2026-04-17 01:19:45 +00:00

mvhutz changed title from feat!: `Table.Drop` returns `bool`, `Table.Put` doesn't cause stack-overflow to feat!: `Table.Drop` returns `bool`, `Table.Put` doesn't stack-overflow 2026-04-17 01:19:51 +00:00

mvhutz changed title from feat!: `Table.Drop` returns `bool`, `Table.Put` doesn't stack-overflow to feat!: `Drop` returns `bool`, `Put` doesn't stack-overflow 2026-04-17 01:20:02 +00:00

mvhutz merged commit 39548b4332 into main 2026-04-17 01:31:02 +00:00

mvhutz deleted branch feat/safe-put 2026-04-17 01:31:02 +00:00

mvhutz referenced this issue from a commit 2026-04-17 01:31:03 +00:00

feat!: `Drop` returns `bool`, `Put` doesn't stack-overflow (#21)

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

bug

Something is not working

duplicate

This issue or pull request already exists

enhancement

New feature

help wanted

Need some help

invalid

Something is wrong

question

More information is needed

wontfix

This won't be fixed

No labels

Milestone

No items

No Milestone

Assignees

Clear assignees

mvhutz (Maxim Hutz)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: tools/go-cuckoo#21