Crate rkyv[−][src]

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.

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, and archived values can be truly deserialized with Deserialize if full mutation capabilities are needed.

Type support

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.

rkyv also has support for contextual serialization, deserialization, and validation. It can properly serialize and deserialize shared pointers like Rc and Arc, and can be extended to support custom contextual types.

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.

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 lengths
size_64: Archives *size as *64 instead of *32. This is for large archive support
std: 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 through bytecheck

Examples

See Archive for examples of how to use rkyv.

Modules

core_impl	`Archive` implementations for core types.
de	Deserialization traits, deserializers, and adapters.
ser	Serialization traits, serializers, and adapters.
std_impl	`Archive` implementations for std types.
util	Utilities for common archive operations.
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 16 bytes.
AlignedVec	A vector of bytes that aligns its memory to 16 bytes.
Infallible	A fallible type that cannot produce errors
RawRelPtr	An untyped pointer which resolves relative to its position in memory.
RelPtr	A pointer which resolves to relative to its position in memory.

Enums

Unreachable

An error that can never be produced

Traits

Archive	A type that can be used without deserializing.
ArchiveCopy	An `Archive` type that is a bitwise copy of itself and without additional processing.
ArchivePointee	An archived type with associated metadata for its relative pointer.
ArchiveUnsized	A counterpart of `Archive` that’s suitable for unsized types.
Deserialize	Converts a type back from its archived form.
DeserializeUnsized	A counterpart of `Deserialize` that’s suitable for unsized types.
Fallible	Contains the error type for traits with methods that can fail
Serialize	Converts a type to its archived form.
SerializeUnsized	A counterpart of `Serialize` that’s suitable for unsized types.

Functions

archived_unsized_value ^⚠	Casts a `RelPtr` to the given unsized type from the given byte array at the given position and returns the value it points to.
archived_unsized_value_mut ^⚠	Casts a mutable `RelPtr` to the given unsized type from the given byte array at the given position and returns the value it points to.
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.
check_archive	Checks the given archive at the given position for an archived version of the given type.

Type Definitions

Archived	Alias for the archived version of some `Archive` type.
ArchivedIsize	The type used for offsets in relative pointers.
ArchivedMetadata	Alias for the archived metadata for some `ArchiveUnsized` type.
ArchivedUsize	The type used for sizes in archived types.
MetadataResolver	Alias for the metadata resolver for some `ArchiveUnsized` type.
Resolver	Alias for the resolver for some `Archive` type.

Derive Macros

Archive	Derives `Archive` for the labeled type.
Deserialize	Derives `Deserialize` for the labeled type.
Serialize	Derives `Serialize` for the labeled type.