archive only.Expand description
In-tree zero-copy archive codec (replaces the rkyv dependency).
In-tree zero-copy archive codec (replaces the rkyv dependency).
§Layout
The archive payload is a flat byte buffer with a root-first, positive relative-offset layout — an original design distinct from rkyv’s root-at-end placement:
payload:
[ root skeleton (fixed-size fields) ] <- root lives at offset 0
[ data region: string / vec bodies ]Every variable-width field in a struct is a
crate::archive_codec::RelPtr: a signed 32-bit
byte offset from the field’s own address to its data. Because the data
region always follows the struct that references it, offsets are positive
and the pointer math is monotonic.
- A
Stringbody isu32 byte_lenfollowed by UTF-8 bytes. - A
Vec<T>body isu32 count, padding toalign_of::<T>(), thencountTelements. The padding keeps the element array aligned socrate::archive_codec::ArchivedVec::as_slicecan build a&[T]without an unaligned read. - Archived structs are fixed-size mirrors of their source (primitives
inline, strings and vecs as
crate::archive_codec::RelPtr), so aVec<Reading>is a contiguous array of fixed-sizecrate::archive_codec::ArchivedVecelements.
§Two-phase serialization
A struct is written in two phases so that Vec<T> elements stay
contiguous: the skeleton phase writes the fixed-size fields (inline
primitives plus RelPtr placeholders for every variable-width field) and
records the placeholder positions; the bodies phase writes the actual
string/vec data and patches each placeholder. Nested structs recurse into
the same two phases through a shared position queue.
§Safety model
The only unsafe is from_raw_parts for slices of archived primitives
and from_utf8_unchecked for validated strings, both reached only after
crate::archive_codec::CheckBytes has proven every offset, length, and range in-bounds. The
backing buffer is ALIGN-aligned (see the archive envelope), so the root
and every element array start on an alignment boundary.
Archived mirrors stay borrowed in place; copying a relative-pointer field to another address would invalidate its targets.
use rustbinary::archive::Archive;
#[derive(Archive)]
struct Record { text: String }
fn require_copy<T: Copy>() {}
require_copy::<ArchivedRecord>();use rustbinary::archive::Archive;
#[derive(Archive)]
struct Record { text: String }
fn require_clone<T: Clone>() {}
require_clone::<ArchivedRecord>();Structs§
- Archive
Serializer - Serializer that produces the flat archive payload.
- Archived
String - The archived form of a UTF-8 string.
- Archived
Vec - The archived form of a
Vec<T>. - RelPtr
- A signed 32-bit byte offset from a field’s own address to its data.
Traits§
- Archive
- The archive schema contract: the archived mirror type.
- Archive
Write - The archival serialization contract.
- Archived
Value - Marker for archived values whose in-memory representation is their wire layout and which can therefore be read as a contiguous slice.
- Check
Bytes - Validates an archived value.
- Pod
- Plain-data value serialized by its little-endian byte representation.
Functions§
- check_
skeleton - Checks the entire fixed-size representation, including trailing padding, before a validator walks fields or constructs a typed reference.
- check_
string_ field - Checks a
Stringfield: readsu32 lenat the target and verifies the UTF-8 bytes fit. - check_
vec_ field - Checks a
Vec<T>field of fixed-size elements: readsu32 countat the target, skips the alignment padding, and verifies the element slice fits. - check_
vec_ nested - Checks a
Vec<T>field of nested archived structs: verifies the element slice fits (including alignment padding) and recursively validates each element. - to_
archive - Convenience: serializes a root value into a fresh payload.
- vec_
elements_ offset_ of - The alignment helper for a concrete element type, mirroring the private
vec_elements_offsetused by the writer and validators (crate-private, so not linkable from public docs).