Expand description
Bounded QSync content scan (SVC-01.16 partial).
Logical size is a u64. Admitted resident is a u32 cap (4 MiB), never a
buffer allocated to that size or to logical_bytes. Each page copies into a
caller-owned buffer of at most MAX_PAGE_BYTES. This is not RAM-sized
materialization and is not a complete QSync package.
Declared limits: wire delivery is at-least-once (a QdnfError::Capacity
does not advance the cursor, so the same offset may be re-offered). Local
application of Ok(n > 0) is at-most-once for this cursor (offset advances).
Not exactly-once. Continuations do not refill remaining caps. Cancelled
complete cannot resurrect.
Structs§
- Scan
Budget - Remaining scan quanta. Continuations must not refill these fields.
- Scan
Cursor - Copy cursor: operation id, logical offset, generation, remaining budget.
Constants§
- MAX_
PAGES - Maximum pages charged against one remaining
ScanBudget. - MAX_
PAGE_ BYTES - Maximum bytes copied into one caller page.
- Q42_
QUINS_ PER_ SUPERBLOCK - Maximum 48-byte
NQuins stored in one.q42SuperBlock. - Q42_
SUPERBLOCK_ BYTES - Canonical
.q42SuperBlock byte size (853NQuins × 48 B + 16 B tail padding). - RESIDENT_
CAP_ BYTES - Admitted resident ceiling. Not a dataset size and not an allocated buffer.
Functions§
- admit_
scan - Admit a page-sized exclusive lease (never
logical_bytes) for this scan. - allocation_
class_ hot_ zero_ heap next_pagecopies into caller-ownedoutwith noVec/String/Box.- at_
least_ once_ delivery - Pages may be re-offered after Capacity if the cursor was not advanced.
- at_
most_ once_ local_ application - Once
Ok(n > 0)returns, a laternext_pageuses a higher offset. - cancel_
scan - Stop further pages. A cancelled cursor cannot resume as if cancel never happened. Idempotent.
- cancel_
scan_ in - Cancel the cursor and the admitted operation, if present.
- complete_
scan - Finish the admitted scan. After cancel this releases storage and returns
QdnfError::Cancelledso a late page is not a live success. - continuation_
refills_ budget - Continuations never restore pages/work/bytes.
- next_
page - Copy the next page into
outusing the synthetic XOR fill. - next_
page_ from - Copy the next page from
sourceviaScanSource::read_atatcursor.offset. - next_
page_ in - Gate further pages on
OperationTablecancel. Table cancel stops pages. - open_
production_ scan - Open a production scan bound to
source. Requires a non-zero source digest. - open_
scan - Open a scan over a logical size. Never materializes
logical_bytes. - open_
scan_ bound - Open a scan bound to an authenticated source identity (not computed here).
- production_
scan_ uses_ synthetic_ xor - Production scans copy through
ScanSource, never the XOR fill. - ram_
sized_ dataset_ materialized - This module never allocates or maps a RAM-sized logical dataset.
- scan_
pages_ are_ storage_ evidence - True only when
open_scan_boundattached a non-zero source digest. - synthetic_
scan_ is_ storage_ evidence - Synthetic XOR
next_pagefill is never storage evidence. - verify_
superblock_ slice_ parity_ and_ sha256 - Verify a
.q42SuperBlock slice against its expected SHA-256 Merkle chain digest and verify canonical 5-fieldNQuinXOR parity (s ^ p ^ o ^ c ^ m) on every 48-byte Quin in the slice (R08).