Skip to content

refactor: use hashcrew CRC and remove Tokio runtime coupling - #53

Draft
tisonkun wants to merge 3 commits into
mainfrom
codex/hashcrew-runtime-independent
Draft

tisonkun wants to merge 3 commits into
mainfrom
codex/hashcrew-runtime-independent

Conversation

@tisonkun

@tisonkun tisonkun commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Upgrade Hashcrew to 0.3.0 and use its CRC32C implementation without changing persisted checksums or the disk format.
  • Remove Tokio from the library's dependencies and the logging example. Cache futures now work with any executor; replace Cache::open_with_handle(path, config, handle) with Cache::open(path, config).

Design Notes

Opening and closing each use a short-lived lifecycle thread and an AsyncBand channel with capacity one. Close still fences admission immediately and completes even if its returned future is never polled or is dropped. The bounded channel keeps the completion handoff visible to ThreadSanitizer; AsyncBand 0.7's oneshot uses atomic fences, which ThreadSanitizer does not support.

A shared async-io::Timer preserves read admission deadlines, I/O cancellation grace periods, and FIFO admission. These waits bound existing operations; no request-path retries are introduced. Lifecycle thread stacks and timer infrastructure remain outside the managed-memory budget. Using an independent timer adds async-io and its transitive dependencies.

Tokio remains in tests and benchmarks, and crc-fast remains only as an independent test reference. Tests cover driverless open/read/recovery/close, cache use after its opening executor is dropped, deadline wakeups and capacity reclamation, lifecycle cancellation and panics, and CRC compatibility for fragmented records and pages.

Validation: cargo x check, cargo x lint --fix (including packaging and dependency policy checks), cargo +1.98.0 x test (including extended tests), cargo +1.98.0 test --workspace --release --all-features, and benchmark compilation passed locally. Normal/build dependency trees on macOS and Linux contain neither Tokio nor crc-fast.

Local benchmark: Apple M4 Max, macOS 26.6.2, Rust 1.98.0; five alternating-order pairs comparing 03d4fde with 3f875e3. The existing cache benchmark used 32,768 entries of 16 KiB, 1 GiB L2, 256 MiB L1, buffered POSIX I/O, four read workers, and statistics disabled. Each L2 phase reads every entry once; the resident L1 phase performs 262,144 reads. Immediate uses four L2 clients; Wait uses eight clients, a 100 ms admission timeout, and capacity for 16 waiters. Medians:

L2 admission main ops/s PR ops/s Change P99, main → PR
Immediate 189,594 176,229 -7.0% 65.536 → 65.536 µs
Wait 193,407 175,008 -9.5% 131.072 → 131.072 µs

The L2 throughput regression remains a review tradeoff for removing runtime coupling. In the same Immediate/Wait runs, put-plus-drain throughput changed by -5.8%/+2.0%, resident L1 by +4.5%/-0.6%, and warm-close time by 126→145 ms / 131→139 ms. All runs passed value/tier validation and L2 reads reported no errors. Percentiles are log2 histogram upper bounds. These short warm-page-cache runs are local preflight evidence, not Linux/NVMe qualification or proof of equivalent performance.

@tisonkun
tisonkun marked this pull request as draft September 15, 2026 08:06
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