[−][src]Crate rkyv
rkyv
rkyv (archive) is a zero-copy deserialization framework for Rust.
It's similar to other zero-copy deserialization frameworks such as Cap'n Proto and FlatBuffers. However, while the former have external schemas and heavily restricted data types, rkyv allows all serialized types to be defined in code and can serialize a wide variety of types that the others cannot. Additionally, rkyv is designed to have little to no overhead, and in most cases will perform exactly the same as native types.
rkyv has a hashmap implementation that is built for zero-copy deserialization, so you can serialize your hashmaps with abandon. The implementation performs perfect hashing with the compress, hash and displace algorithm to use as little memory as possible while still performing fast lookups.
One of the most impactful features made possible by rkyv is the ability to
serialize trait objects and use them as trait objects without
deserialization. See the archive_dyn
crate for more details.
Design
Like serde, rkyv uses Rust's powerful trait system to
serialize data without the need for reflection. Despite having a wide array
of features, you also only pay for what you use. If your data checks out,
the serialization process can be as simple as a memcpy
! Like serde, this
allows rkyv to perform at speeds similar to handwritten serializers.
Unlike serde, rkyv produces data that is guaranteed deserialization free. If
you wrote your data to disk, you can just mmap
your file into memory, cast
a pointer, and your data is ready to use. This makes it ideal for
high-performance and IO-bound applications.
Limited data mutation is supported through Pin
APIs. Archived values can
be truly deserialized with Unarchive
if full mutation capabilities are
needed.
Tradeoffs
rkyv is designed primarily for loading bulk game data as efficiently as possible. While rkyv is a great format for final data, it lacks a full schema system and isn't well equipped for data migration. Using a serialization library like serde can help fill these gaps, and you can use serde with the same types as rkyv conflict-free.
Features
const_generics
: Improves the trait implementations for arrays with support for all lengthslong_rel_ptrs
: Increases the size of relative pointers to 64 bits for large archive supportstd
: Enables standard library support (enabled by default)strict
: Guarantees that types will have the same representations across platforms and compilations. This is already the case in practice, but this feature provides a guarantee. It additionally provides C type compatibility.validation
: Enables validation support throughbytecheck
Examples
See Archive
for examples of how to use rkyv.
Re-exports
pub use validation::check_archive; |
pub use validation::ArchiveContext; |
Modules
core_impl |
|
std_impl |
|
validation | Validation implementations and helper types. |
Macros
offset_of | Calculates the offset of the specified field from the start of the named struct. |
Structs
Aligned | Wraps a type and aligns it to at least 16 bytes. Mainly used to align byte buffers for ArchiveBuffer. |
ArchiveBuffer | Wraps a byte buffer and writes into it. |
ArchiveWriter | Wraps a type that implements |
CopyResolver | A resolver that always resolves to the unarchived value. This can be useful
while implementing |
RelPtr | A pointer which resolves to relative to its position in memory. |
Enums
ArchiveBufferError | The error type returned by an |
Traits
Archive | Writes a type to a |
ArchiveCopy | A trait that indicates that some |
ArchiveRef | This trait is a counterpart of |
Resolve | Creates an archived value when given a value and position. |
Seek | A writer that can seek to an absolute position. |
Unarchive | Converts a type back from its archived form. |
UnarchiveRef | A counterpart of |
Write | A |
Functions
archived_ref⚠ | Casts an archived reference from the given byte array at the given position. |
archived_ref_mut⚠ | Casts a mutable archived reference from the given byte array at the given position. |
archived_value⚠ | Casts an archived value from the given byte array at the given position. |
archived_value_mut⚠ | Casts a mutable archived value from the given byte array at the given position. |
Type Definitions
Archived | Alias for the archived version of some |
Offset | The type used for offsets in relative pointers. |
Reference | Alias for the reference for some |
ReferenceResolver | Alias for the resolver of the reference for some |
Resolver | Alias for the resolver for some |
Derive Macros
Archive | Derives |
Unarchive | Derives |