refactor(io): introduce composable high-performance storage architecture by LHT129 · Pull Request #2793 · antgroup/vsag

LHT129 · 2026-08-27T06:21:10Z

Change Type

Linked Issue

Closes: [improve](io): introduce composable high-performance storage access architecture #2818

Why

BasicIO<Derived> currently owns dispatch, logical size, serialization state, range validation, cache orchestration, result ownership, compatibility APIs, and backend fallbacks. Concrete IO classes then repeat file or memory lifecycle logic while mixing the storage medium with single-read, batch-read, durability, direct-I/O, and cache strategies.

This works for the existing set of local profiles, but makes the next steps—deeper io_uring support, truly asynchronous reads, batch-aware shared caches, remote Readers, and additional storage backends—hard to add without duplicating complete IO classes or putting runtime abstraction into hot paths.

The goal of this refactor is to separate those responsibilities while preserving the current performance model: static composition, borrowed zero-copy reads, native backend batching, and no virtual dispatch or generic heap-allocated completion on hot paths.

Architecture after the refactor

Public IO profile (MemoryIO / BufferIO / AsyncIO / UringIO / ReaderIO / ...)
                                  │
                                  ▼
                    ByteIO<Backend, CachePolicy>
                     │      │             │
                     │      │             └─ hit/miss planning, single-flight,
                     │      │                batch refill, invalidation
                     │      └─ logical size, bounds, serialization,
                     │         compatibility adapters
                     ▼
             storage-specific Backend
       ┌─────────────┼─────────────────────────────────────┐
       ▼             ▼                                     ▼
 Contiguous      PosixFileBackend                    External/NonContinuous
 Backend         <SingleRead, BatchRead,             Reader backends
 <Region>         Durability>
   │                │
   ├─ HeapRegion    ├─ Buffered / Direct / Configurable single read
   └─ MMapRegion    ├─ Sequential / libaio / io_uring batch read
                    └─ NoFlush / FsyncAfterWrite

Cross-cutting value types:
  ReadRequest ── ReadLease ── ReadOperation ── IOEnvironment

The architecture has six explicit boundaries:

ByteIO<Backend, CachePolicy> owns logical size, overflow-safe range checks, serialization flow, cache invalidation, and compatibility adapters. Its template composition keeps disabled features removable at compile time.
Backends own physical storage and expose explicit capabilities. Implementations cover heap/mmap contiguous regions, block memory, POSIX files, external Readers, and non-contiguous logical-to-physical mapping.
File policies separate single-read mode, batch engine, and write durability. BufferIO, AsyncIO, and UringIO are supported static profiles rather than independent implementations of the whole IO contract.
ReadLease represents borrowed, allocator-owned, aligned, cached, and configurable ownership as move-only RAII values. Internal DataCell and algorithm hot paths no longer manually pair need_release with Release().
ReadOperation provides an immediate completion for synchronous paths and a stable operation boundary for asynchronous engines without forcing synchronous reads to allocate.
CachePolicy plans unique page misses, preserves backend ReadMany batching, coordinates single-flight loads, isolates shared-cache namespaces, and compiles to a direct backend path when disabled.

IOKind and VisitIOKind centralize the cold-path mapping from configured IO type to the finite set of supported C++ profiles. Users keep the existing IO type strings; arbitrary policy combinations are intentionally not exposed.

What Changed

Replaced the old BasicIO implementation hierarchy with statically composed ByteIO profiles.
Added explicit storage backends for heap/mmap regions, block memory, POSIX files, external Readers, and non-contiguous mappings.
Split file access into buffered/direct/configurable single-read, sequential/libaio/io_uring batch-read, and durability policies.
Added move-only leases and operation types for explicit ownership and completion.
Added NoCache and batch-aware OptionalPageCache, including duplicate-miss coalescing, shared single-flight coordination, failure recovery, and namespace-safe invalidation.
Migrated MemoryIO, MemoryBlockIO, MMapIO, BufferIO, AsyncIO, UringIO, ReaderIO, NonContinuousIO, DataCell accessors, layouts, serialization, and IO type dispatch.
Preserved the public IO class names, parameter keys, fallback profiles, and existing APIs as compatibility boundaries.
Removed the old BasicIO implementation and migration-only duplicate paths after differential and performance gates passed.
Added contract, randomized differential, compatibility, concurrency, exception-safety, fault-injection, and end-to-end coverage.

Compatibility Impact

API/source compatibility: existing public IO class names and existing read/release entry points are retained.
Configuration compatibility: existing JSON IO type names and parameters are retained; no-aio/no-uring fallbacks remain supported.
Serialization compatibility: baseline/candidate cross-load tests pass in both directions; end-to-end comparisons load one baseline-generated serialized input in both builds.
Behavior changes: canonical APIs use strict range validation. The buffered compatibility path preserves its historical unchecked-read behavior to avoid changing semantics and syscall-path cost.
Internal ownership: DataCell and algorithm hot paths use RAII leases or caller-owned buffers instead of manual release flags.

Performance and Concurrency Impact

All authoritative runtime comparisons were run on Linux lht.dev with an Intel Xeon Platinum 8269CY, GCC 11.4, fixed CPU affinity, byte-identical benchmark sources, alternating order, matched inputs, and checksum validation. Timing claims use multi-sample medians; shared-host direct-I/O tail noise is reported rather than hidden.

End-to-end

Workload	Baseline	Current	Delta
HGraph async read-cache	1,203.409 us	846.410 us	-29.67%
RaBitQ hybrid	2,315.273 us	1,923.664 us	-16.91%
RaBitQ memory, long window	1,180.887 us	1,187.346 us	+0.55%, below dispersion
SINDIV2 async term/rerank	808.714 us	809.787 us	+0.13%, within dispersion
RaBitQ direct async	22,600.043 us	22,828.289 us	+1.01%, O_DIRECT tail noise reverses by run order

Checksums match for every workload. No stable end-to-end regression was observed.

Representative hot paths

Operation	Baseline	Current	Delta
Buffer copy 128 B	386.292 ns	371.629 ns	-3.80%
Buffer copy 4 KiB	1,025.883 ns	1,017.985 ns	-0.77%
Buffer acquire 128 B	424.236 ns	401.130 ns	-5.45%
Buffer batch 128 B	11,754.770 ns	11,655.867 ns	-0.84%
Buffer batch 4 KiB	32,942.458 ns	32,960.923 ns	+0.06%

MemoryIO copy/acquire is within ±0.4% across 32 B–4 KiB. Release assembly for borrowed acquire contains no call, indirect dispatch, allocator operation, cache operation, or lease-destructor call.
MemoryBlock same-block acquire is about 1.1% faster; cross-block results are within -0.02% to +1.4% with identical allocation counts.
Cache hits improve by 3.6%–64%; cache-miss batches by 31%–35%; duplicate-miss batches by 18%–37%.
NonContinuousIO improves by 2.45%–21.9% across the final baseline/candidate profiles and uses zero project-allocator calls for normal batches.

Syscalls, submissions, allocation, and size

Buffer write: 1 syscall before and after.
100 buffered reads: 100 pread calls before and after.
100 batches of eight buffered requests: 800 pread calls before and after.
libaio: 237 requests in 3 submissions before and after.
io_uring: 1,037 requests in 3 submissions before and after.
Direct/buffered ownership allocation counts are identical for corresponding profiles.
Tradeoff: static library size is +3.1%; shared library size is +4.3% due to explicit static profile instantiations.

The cache's single-flight state and shared namespace coordination are protected explicitly. Reads may run concurrently when the backend supports them; resize/remap/write still require the documented external synchronization. TSan concurrency-focused tests report no race or deadlock.

The benchmark and syscall/submission probe sources used for these acceptance measurements are preserved on the contributor branch refactor/io-composable-architecture-with-bench-probes; they are intentionally excluded from this PR's merge diff.

Test Evidence

Key results:

Default Debug non-long:       825 cases / 85,379,810 assertions, PASS
Post-fast-path focused Debug:  24 cases /    114,378 assertions, PASS
Explicit liburing:             49 cases /    125,138 assertions, PASS
No aio / no io_uring:          48 cases /    125,144 assertions, PASS
ASan + UBSan:                  49 cases /    125,138 assertions, PASS
TSan focused:                  33 cases /    117,018 assertions, PASS
Latest ReaderIO regression:     8 cases /      1,097 assertions, PASS
src/io coverage: 59.9% lines / 50.1% functions

Long-running [daily] and [tune] suites were intentionally excluded; the acceptance matrix uses targeted correctness, sanitizer, backend-configuration, and representative performance tests instead.

Documentation Impact

No repository documentation files are included; architecture and validation details are kept in this PR description.

Risk and Rollback

Risk level: high, because this replaces the IO core and migrates its consumers.
Primary risks: serialization drift, ownership/lifetime mistakes, cache batching regressions, async failure cleanup, and template-driven binary growth.
Mitigations: bidirectional serialization tests, randomized differential tests, RAII leases, backend failure-path validation, sanitizers, TSan, fixed-CPU paired benchmarks, and retained compatibility entry points.
Rollback plan: revert the single refactor commit. Public configuration and serialization formats remain compatible, so persisted indexes do not require migration.

Checklist

I have linked the relevant issue
I have added/updated tests for new behavior and bug fixes
I have considered API and serialization compatibility impact
I have documented architecture and validation in the PR description
My commit follows Conventional Commits and contains DCO sign-off

vsag-bot · 2026-08-27T06:21:15Z

/label status/waiting-for-review
/waiting-on reviewer
/request-review @jiaweizone
/request-review @wxyucs
/request-review @inabao

mergify · 2026-08-27T06:21:44Z

Merge Protections

🟢 All 2 merge protections satisfied — ready to merge.

Show 2 satisfied protections

🟢 Require kind label

label~=^kind/

🟢 Require version label

label~=^version/

Copilot

Pull request overview

Refactors VSAG’s IO subsystem from the duplicated BasicIO hierarchy into a statically composed ByteIO<Backend, CachePolicy> architecture, migrating existing IO types while preserving public names/config/serialization behavior and adding targeted tests + IO microbench harnesses.

Changes:

Introduces composable IO core (backends, policies, leases, request/operation types) and migrates Memory/Block/MMap/Buffer/Async/Uring/Reader IO to V2 profiles behind stable aliases.
Updates layouts/datacells/algorithms to use lease-based reads and centralized IO kind/type dispatch (IOKind, VisitIOKind).
Adds IO benchmark targets (gated by ENABLE_IO_BENCHMARKS) and uploads IO perf CSV artifacts in the performance workflow.

Reviewed changes

Copilot reviewed 116 out of 136 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
TASK.md	POC plan/status notes for IO refactor
src/reader.cpp	Adjust Reader multi-read error message
src/layout/variable_record_layout.h	Switch to concrete IO + add Acquire leases
src/layout/fixed_layout.h	Switch to concrete IO + add Acquire/AcquireRange
src/layout/fixed_layout_test.cpp	Update test IO + validate Acquire APIs
src/layout/byte_range_layout.h	Switch to concrete IO + add Acquire, Size()
src/io/uring_io/uring_io.h	Alias UringIO to UringIOV2
src/io/uring_io/uring_io_v2.h	New UringIO V2 profile composition
src/io/uring_io/uring_io_test.cpp	Use IO contract tests for uring
src/io/uring_io/uring_io_read_object.h	Remove legacy uring read helper
src/io/uring_io/uring_io_read_object.cpp	Remove legacy uring read helper impl
src/io/uring_io/uring_io_context_guard.cpp	Remove legacy uring context guard
src/io/reader_io/reader_io.h	Alias ReaderIO to ReaderIOV2
src/io/reader_io/reader_io.cpp	Remove legacy ReaderIO impl
src/io/reader_io/reader_io_v2.h	New ReaderIO V2 declaration
src/io/reader_io/reader_io_v2.cpp	New ReaderIO V2 implementation
src/io/reader_io/reader_io_test.cpp	Update ReaderIO tests for V2 contract
src/io/read_cache/page_cache.h	Add RemoveRange API
src/io/read_cache/page_cache.cpp	Implement RemoveRange and stale marking
src/io/policy/uring_batch_read.h	New io_uring batch-read policy wrapper
src/io/policy/sequential_batch_read.h	New sequential batch-read policy
src/io/policy/libaio_batch_read.h	New libaio batch-read policy wrapper
src/io/policy/durability_policy.h	Add durability policies (NoFlush/Fsync)
src/io/policy/configurable_single_read.h	Add configurable single-read + Acquire
src/io/policy/buffered_single_read.h	Add buffered single-read + Acquire/LegacyRead
src/io/noncontinuous_io/noncontinuous_io_test.cpp	Update contract tests + add spill coverage
src/io/mmap_io/mmap_io.h	Alias MMapIO to MMapIOV2
src/io/mmap_io/mmap_io_v2.h	New MMapIO V2 profile composition
src/io/mmap_io/mmap_io_v2_test.cpp	New MMapIOV2 contract/compat tests
src/io/mmap_io/mmap_io_test.cpp	Use IO contract tests for mmap
src/io/memory_io/memory_io.h	Alias MemoryIO to MemoryIOV2
src/io/memory_io/memory_io.cpp	Remove legacy MemoryIO impl
src/io/memory_io/memory_io_v2.h	New MemoryIO V2 profile composition
src/io/memory_io/memory_io_test.cpp	Use IO contract tests for memory
src/io/memory_block_io/memory_block_io.h	Alias MemoryBlockIO to MemoryBlockIOV2
src/io/memory_block_io/memory_block_io.cpp	Remove legacy MemoryBlockIO impl
src/io/memory_block_io/memory_block_io_v2.h	New MemoryBlockIO V2 profile composition
src/io/memory_block_io/memory_block_io_test.cpp	Use IO contract tests for block memory
src/io/io_headers.h	Replace legacy include with type dispatch
src/io/core/uring_read_operation.h	New uring operation type
src/io/core/read_request.h	New ReadRequest type
src/io/core/read_operation.h	Replace legacy uring guard with ImmediateOperation
src/io/core/read_lease.h	New lease/owner types for Acquire
src/io/core/io_utils.h	New IO range helpers (CheckedEnd/IsValidRange)
src/io/core/io_environment.h	New IOEnvironment + default pools
src/io/core/cached_read_operation.h	Cache-wrapped operation variant
src/io/core/cached_read_lease.h	Cache-wrapped lease variant
src/io/container/io_array_test.cpp	Use IO contract tests
src/io/common/io_type_dispatch.h	New VisitIOKind dispatch helper
src/io/common/io_type_dispatch_test.cpp	Tests for VisitIOKind mapping
src/io/common/io_parameter.h	Add IOKind + Kind/KindFromName
src/io/common/io_parameter.cpp	Switch parsing to KindFromName + add Kind()
src/io/common/io_parameter_test.cpp	Tests for KindFromName mapping
src/io/common/io_contract_test.h	Update contract tests to V2 IO types
src/io/CMakeLists.txt	Update IO sources (remove legacy, add new)
src/io/cache/no_cache.h	New NoCache policy
src/io/buffer_io/buffer_io.h	Alias BufferIO to BufferIOV2
src/io/buffer_io/buffer_io.cpp	Remove legacy BufferIO impl
src/io/buffer_io/buffer_io_v2.h	New BufferIO V2 profile composition
src/io/buffer_io/buffer_io_test.cpp	Update BufferIO tests for V2 API
src/io/backend/posix_file.h	New PosixFile RAII wrapper
src/io/backend/posix_file.cpp	PosixFile open/truncate/ownership logic
src/io/backend/posix_file_backend.h	New POSIX file backend template
src/io/backend/mmap_region.h	New mmap region backend
src/io/backend/mmap_region.cpp	mmap region implementation
src/io/backend/heap_region.h	New heap region backend
src/io/backend/contiguous_backend.h	New contiguous backend wrapper
src/io/async_io/direct_io_object.h	Remove legacy direct IO helper
src/io/async_io/async_io.h	Alias AsyncIO to AsyncIOV2
src/io/async_io/async_io_v2.h	New AsyncIO V2 profile composition
src/io/async_io/async_io_test.cpp	Update AsyncIO tests for V2 API
src/impl/filter/extrainfo_wrapper_filter.cpp	Use ExtraInfo lease-based access
src/datacell/sparse_vector_datacell.inl	Use layout leases + Kind-based IO strategy
src/datacell/sparse_vector_datacell.h	Update IO ownership/type + add ReadLease alias
src/datacell/rabitq_split_datacell_factory_impl.h	Kind-based IO combination checks + dispatch
src/datacell/multi_vector_datacell.h	Remove BasicIO dependency
src/datacell/graph_interface.cpp	Kind-based IO dispatch for GraphDataCell
src/datacell/graph_datacell.h	Store concrete IO shared_ptr
src/datacell/flatten_interface.h	Add RAII lease wrapper for codes
src/datacell/flatten_interface.cpp	Kind-based IO dispatch for flatten cells
src/datacell/flatten_datacell.h	Use layout Acquire APIs
src/datacell/extra_info_interface.h	Add ExtraInfoLease + Acquire API
src/datacell/extra_info_interface.cpp	Use Kind() in ExtraInfo instance creation
src/datacell/extra_info_interface_test.cpp	Update tests to use Acquire leases
src/datacell/extra_info_datacell.h	Store concrete IO shared_ptr in SetIO
src/datacell/disk_sindi_term_datacell.h	Store concrete IO shared_ptr
src/datacell/disk_sindi_term_datacell.cpp	Kind-based IO dispatch + mmap lease access
src/datacell/bucket_interface.cpp	Kind-based IO dispatch for buckets
src/datacell/bucket_datacell.h	Replace read/release with Acquire leases
src/datacell/bucket_datacell_test.cpp	Update tracking IO to V2-style MemoryIO base
src/analyzer/pyramid_analyzer.cpp	Use AcquireCodesById lease helper
src/algorithm/pyramid/pyramid.cpp	Use AcquireCodesById lease helper
src/algorithm/hgraph/hgraph.cpp	Use AcquireCodesById lease helper
src/algorithm/hgraph/hgraph_mci.cpp	Use AcquireCodesById lease helper
src/algorithm/bruteforce/bruteforce.cpp	Use AcquireCodesById lease helper
CMakeLists.txt	Add optional IO benchmark subdir
cmake/VSAGOptions.cmake	Add ENABLE_IO_BENCHMARKS option
benchs/io/io_syscall_count_probe.cpp	New syscall-count probe benchmark
benchs/io/io_codegen_probe.cpp	New codegen/ABI probe for IO hot paths
benchs/io/CMakeLists.txt	Add IO benchmark/probe targets
.github/workflows/performance.yml	Build/run IO benchmarks and upload CSV artifacts

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

Pull request overview

Copilot reviewed 116 out of 136 changed files in this pull request and generated 1 comment.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

LHT129

Code review for commit 4a68c44

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Separate storage backends, access and cache policies, ownership leases, and completion operations while preserving public IO profiles and serialization compatibility. Keep hot paths statically composed, retain native batch submission, and add differential, sanitizer, concurrency, and compatibility validation. Co-authored-by: opencode <opencode@anthropic.com> Signed-off-by: LHT129 <tianlan.lht@antgroup.com>

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

LHT129

Code review for the composable IO architecture refactor.

LHT129

Code review for the composable IO architecture refactor.

Copilot AI lite review requested due to automatic review settings August 27, 2026 06:21

vsag-bot assigned LHT129 Aug 27, 2026

pull-request-size Bot added the size/XXL label Aug 27, 2026

Copilot started reviewing on behalf of LHT129 August 27, 2026 06:21 View session

Copilot AI reviewed Aug 27, 2026

View reviewed changes

Comment thread src/datacell/extra_info_interface.h

Copilot AI review requested due to automatic review settings August 28, 2026 06:39

LHT129 force-pushed the refactor/io-composable-architecture branch from e43961c to 7f31f45 Compare August 28, 2026 06:39

Copilot started reviewing on behalf of LHT129 August 28, 2026 06:39 View session

Copilot AI reviewed Aug 28, 2026

View reviewed changes

Comment thread benchs/io/io_syscall_count_probe.cpp Outdated

LHT129 commented Aug 28, 2026

View reviewed changes

Comment thread src/io/backend/block_memory_backend.h

LHT129 commented Aug 28, 2026

View reviewed changes

Comment thread src/io/backend/heap_region.h

Copilot AI review requested due to automatic review settings August 31, 2026 06:44

LHT129 force-pushed the refactor/io-composable-architecture branch from 7f31f45 to 9cc29ab Compare August 31, 2026 06:44

Copilot AI reviewed Aug 31, 2026

LHT129 commented Aug 31, 2026

View reviewed changes

Comment thread src/io/backend/posix_file_backend.h Outdated

LHT129 commented Aug 31, 2026

View reviewed changes

Comment thread src/io/core/byte_io.h

Copilot AI review requested due to automatic review settings August 31, 2026 07:29

Copilot AI reviewed Aug 31, 2026

Copilot AI review requested due to automatic review settings August 31, 2026 07:48

Copilot AI reviewed Aug 31, 2026

LHT129 commented Aug 31, 2026

View reviewed changes

Comment thread src/io/backend/noncontinuous_backend.h

LHT129 commented Aug 31, 2026

View reviewed changes

Comment thread src/io/backend/external_reader_backend.h Outdated

LHT129 marked this pull request as ready for review August 31, 2026 08:10

LHT129 requested review from inabao, jiaweizone and wxyucs as code owners August 31, 2026 08:10

LHT129 added kind/cleanup Code refactoring, formatting, or dead code removal 代码重构、格式化或清理无用代码 version/1.1 labels Aug 31, 2026