feat(mmap): Introduce zero-copy memory-mapped file decompression - #349
Draft
hellobertrand wants to merge 4 commits into
Draft
feat(mmap): Introduce zero-copy memory-mapped file decompression#349hellobertrand wants to merge 4 commits into
hellobertrand wants to merge 4 commits into
Conversation
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
hellobertrand
force-pushed
the
feat/mmap-inplace-decode
branch
2 times, most recently
from
July 31, 2026 16:36
48c85f1 to
509c345
Compare
This change introduces a new `zxc_mmap.h` API for decompressing ZXC archives directly from files into memory-mapped regions. This eliminates input staging buffers and separate output allocations, leading to: - Zero-copy reads of compressed data on POSIX systems. - Single-copy reads on Windows (archive copied once to the region). - Significant reductions in peak Resident Set Size (RSS), measured at 24-49%. The API also includes functions to map files read-only, allowing existing buffer APIs to consume on-disk archives without an input copy. A new `ZXC_ERROR_UNSUPPORTED` error code is added for platforms where memory mapping is unavailable.
Introduce true zero-copy memory-mapped decompression for Windows 10 1803 (and Server 2019) and later, leveraging placeholder mappings via `VirtualAlloc2` and `MapViewOfFile3`. These APIs are resolved dynamically at runtime, allowing the library to gracefully fall back to a single archive copy on older Windows versions, maintaining compatibility without increasing minimum OS requirements. Add `zxc_mmap_is_zerocopy()` to report whether the zero-copy route was successfully employed, aiding in deployment observability.
A seekable archive decodes through the mapped path like any other -- the seek table sits behind the EOF block, so the decoder skips it -- but nothing exercised that, and the in-place bound had to reserve the table first (see the preceding fix). mmap_case() gains block_size + seekable parameters, with the biting shape as the regression: 8 MiB of incompressible data in 4 KiB blocks, where the seek table used to exceed the whole margin. For random access the mapped API is not the answer: zxc_decompress_mmap decodes a whole frame. zxc_mmap_open composes with the seekable API instead, as a zero-copy backend for zxc_reader_t whose read_at is a memcpy out of the mapping -- no read() syscall per block, and reentrant, so zxc_seekable_decompress_range_mt is legal on it. Documented in API.md section 7b, with a pointer to it from the seekable-reader example in EXAMPLES.md.
Enhance clarity and maintainability of the memory-mapped decompression subsystem by adding Doxygen-style docstrings to static functions and refactoring platform-specific includes.
hellobertrand
force-pushed
the
feat/mmap-inplace-decode
branch
from
August 12, 2026 19:43
509c345 to
4c890dc
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
2 participants
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.
This change introduces a new
zxc_mmap.hAPI for decompressing zxc archives directly from files into memory-mapped regions. This eliminates input staging buffers and separate output allocations, leading to:The API also includes functions to map files read-only, allowing existing buffer APIs to consume on-disk archives without an input copy. A new
ZXC_ERROR_UNSUPPORTEDerror code is added for platforms where memory mapping is unavailable.