Skip to main content

Module archive_codec

Module archive_codec 

Source
Available on crate feature 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.

§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§

ArchiveSerializer
Serializer that produces the flat archive payload.
ArchivedString
The archived form of a UTF-8 string.
ArchivedVec
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.
ArchiveWrite
The archival serialization contract.
ArchivedValue
Marker for archived values whose in-memory representation is their wire layout and which can therefore be read as a contiguous slice.
CheckBytes
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 String field: reads u32 len at the target and verifies the UTF-8 bytes fit.
check_vec_field
Checks a Vec<T> field of fixed-size elements: reads u32 count at 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_offset used by the writer and validators (crate-private, so not linkable from public docs).