Forkless, background iteration utility (forkless)

[JimB123]

The heart of forkless save (also forkless sync and forkless slot migration) is the bgIteration utility.

bgIteration is responsible for presenting a view of the database, possibly with replication, to achieve the requested consistency.

Important concepts:

• bgIteration is a utility which performs iteration over the database with the intent to present this iteration to a "bgIteration client". It is analogous to any other iterator. It has no specific knowledge of the reason for iteration. It can be used for any purpose.
• A "bgIteration client" receives iteration data from bgIteration. It is expected that the bgIteration client works in the background (on another thread). The bgIteration client is not permitted to modify the data during iteration. The bgIteration client understands the reason for iteration. (Threadsave is the bgIteration client responsible for forkless save - and is not included in this PR.)
• A "consistent" iteration offers point-in-time consistency. This is the type of consistency needed for snapshot (bgsave). In a consistent iteration, all key/value data must be presented (to the bgIteration client) - as it existed at the point of consistency - before any modifications may be permitted.
• A "non-consistent" iteration doesn't maintain consistency from the start of iteration. Instead, it presents key/value pairs as they exist currently in the database. The guarantees are similar to other iterators. If a value is created during the iteration, it may or may not be presented as part of the iteration.
• An iteration may contain replication. Replication is a filtered view of replication which presents replication data related to key/values which have already been iterated (and new values being created). When replication is combined with a non-consistent iteration, it's possible to achieve consistency at the END of the iteration.

The current use case, forkless save, will use a consistent iteration without replication.
Full sync will use a non-consistent iteration, with replication. This allows consistency to be achieved by the end of the syncronization.

There is currently no use case for consistent with replication or non-consistent without replication. However such use cases may be developed in the future. They are fully supported and tested.

Read the documentation in bgiteration.h for more details.

[JimB123]

This replaces previous draft version (which was against a different branch). #3432

[codecov]

Codecov Report

❌ Patch coverage is 59.32203% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.44%. Comparing base (6b8bd41) to head (c930dc5).

Files with missing lines	Patch %	Lines
src/server.c	54.83%	14 Missing ⚠️
src/hashtable.c	20.00%	8 Missing ⚠️
src/defrag.c	50.00%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           forkless    #3553      +/-   ##
============================================
+ Coverage     76.64%   77.44%   +0.79%     
============================================
  Files           159      161       +2     
  Lines         79575    82109    +2534     
============================================
+ Hits          60994    63590    +2596     
+ Misses        18581    18519      -62     

Files with missing lines	Coverage Δ
src/bgiteration.c	92.31% <ø> (ø)
src/db.c	94.60% <100.00%> (+0.23%)	⬆️
src/expire.c	98.13% <100.00%> (+0.01%)	⬆️
src/object.c	87.48% <100.00%> (-3.19%)	⬇️
src/server.h	100.00% <ø> (ø)
src/unit/custom_matchers.hpp	100.00% <100.00%> (ø)
src/unit/test_bgiteration.cpp	99.78% <ø> (ø)
src/defrag.c	80.92% <50.00%> (-0.20%)	⬇️
src/hashtable.c	97.05% <20.00%> (-0.77%)	⬇️
src/server.c	89.47% <54.83%> (-0.03%)	⬇️

... and 14 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[murphyjacob4]

Not a full review - but want to publish some comments to unblock discussion

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8e069dc0-54bc-4510-968b-6eff8a6d02c7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[JimB123]

Status 6/16/2026:

• All pipeline checks passing
• All outstanding comments addressed