Repository navigation
feat(task)!: checksum and sync written blocks at checkpoints - #203
Draft
greenhat616 wants to merge 1 commit into
Draft
greenhat616 wants to merge 1 commit into
greenhat616 wants to merge 1 commit into
Conversation
greenhat616
force-pushed
the
feat/hardening-39-checkpoints
branch
from
November 13, 2026 07:44
cbdec7a to
bf77106
Compare
greenhat616
marked this pull request as draft
November 13, 2026 08:55
The concurrent engine can now record, at checkpoints, which 1 MiB blocks of the partial file are complete, with the CRC32C of each, after the data is synced. This is the mechanism the resume state file (C33) builds on; nothing turns it on yet. Each successful write carries the CRC32C of its bytes, split at block boundaries, computed off the loop thread. Per block, the segments are merged with crc32c_combine as writes arrive. A block with too many segments (64, or 16384 in total) is read back from the file instead. Checkpoints run one at a time, every 8 MiB or 2 s and once at teardown: take the newly complete blocks, sync the writer, read back what needs it, and hand the blocks to a crate-internal receiver. On a failure the receiver rolls back and the blocks are retried at the next checkpoint; if the rollback fails too, checkpointing stops for the task. Failures only warn. Teardown waits for a running checkpoint on every outcome, and its blocking work holds the attempt's drain, so an unwind waits too. Every writer can sync its data: pool, mmap and compio through their drained workers. Without a receiver nothing is checksummed, scheduled or synced. TaskOptions gains checkpoint_bytes and checkpoint_interval. BREAKING CHANGE: in the public file_writer module, WriteCompletion gains the field `crcs`, FileWriterError gains the variant `Sync`, and FileRangeWriter gains `sync`, with a default implementation that returns an Unsupported error. Code that builds a WriteCompletion or matches FileWriterError exhaustively must be updated.
greenhat616
force-pushed
the
feat/hardening-39-checkpoints
branch
from
November 13, 2026 22:25
bf77106 to
e6fb3d2
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
C32 (T21), the second commit of PR-9d (resume) in the download strategy hardening stack. It is stacked on #202, which is its base branch. The design notes are in §11.5.5 (only the checkpoint order and rollback; the state file itself is C33), §11.5.6 (block CRCs), §11.5.13 item 2.2 and §14.28.
Why
A resumable download needs to know which bytes of the partial file are really on disk, and in what state. §11.5.6 does this per 1 MiB block, with a CRC32C that is recorded only after the data is synced. C32 builds that mechanism inside the concurrent engine. C33 connects it to the state file, and C20 reads it back.
What
crc32c0.6.8, which providescrc32c_appendandcrc32c_combine. It has no runtime dependencies. 0.6.9 was published on 2026-11-02, too recently to take now; it can be bumped later. Maintenance facts come from crates.io only.FileRangeWriter::syncis new.Unsupported, so a writer that cannot sync never lets unsynced data be recorded.Command::Sync. Those workers hold the attempt's drain, so an unwind waits for a running sync.FileWriterError::Syncmaps toIoOp::Flush. A sync failure only causes awarn!.WriteCompletion.crcsholds the CRC32C of each successful write, split at block boundaries. It is computed off the loop thread, and only when checkpoints are on. Failed and partial writes carry nothing.BlockCrcs). Segments are kept sorted and never adjacent, and merge with both neighbours throughcrc32c_combine.Checkpoints, owned by the download loop). They run one at a time, every 8 MiB or every 2 s, plus once at teardown.CheckpointReceiver(record,roll_back).roll_backruns and the blocks are retried at the next checkpoint. If the rollback fails as well, checkpointing stops for the task, and the engine stops checksumming and keeping segments. Failures only cause awarn!(Q5).Drained) on every path: return, panic, or being dropped before it runs, read or unread.ResourceChanged, because that data belongs to the old version.TaskOptions::checkpoint_bytesandcheckpoint_interval. They have no effect until C33.ConcurrentTaskInner::checkpoint_to, crate-internal).Onthrough the concurrent engine in C33.Breaking change
The public
file_writermodule, which is public for the benchmarks, changes:WriteCompletiongains the fieldcrcs;FileWriterError, which is not#[non_exhaustive], gains the variantSync;FileRangeWritergainssync, with a default implementation.Code that builds a
WriteCompletionor matchesFileWriterErrorexhaustively stops compiling. The benchmarks in this repository are unaffected.Cost
The benchmark is an ignored release test,
checkpoint_bench.rs::checkpoint_overhead. It uses the mmap writer and runs 5 times per group. It was run on one Windows machine, so confidence is medium.The CRC itself runs at about 17 GiB/s. The cost comes from syncing: the mmap worker cannot write while it syncs. §14.28 records an open item for C33: before checkpoints are enabled, check the default schedule against these numbers. The options are a minimum spacing between checkpoints, a larger
checkpoint_bytes, an mmap flush of only the dirty ranges, and a measurement on slower disks.Tests
record()held by a gate) on ResourceChanged, Cancelled, a failure and Ok.Review
Reviewed with
/ccg:review, using the codex backend only (a single-model review).ResourceChanged, teardown dropped a running checkpoint while its blocking work could still run. Fixed: teardown always settles a running checkpoint, and the work holds the drain. Also fixed:Drained<Work>.Checks
All on
+nightly-2026-11-06, with--no-fail-fast. Clippy allowsunnecessary_lazy_evaluationsuntil #183 merges.cargo fmt --all -- --check.-D warnings.cargo test --workspace --all-features --locked: 28 suites, 853 passed, 1 ignored (the benchmark).cargo test --workspace --locked: 28 suites, 782 passed, 1 ignored.RUSTDOCFLAGS=-Dwarnings cargo doc --no-deps --all-features -p bolt-load: the same 18 errors as its base. It was last run in round 3; round 4 changed only a test and design.md.