Crate rkyv[−][src]
Expand description
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
size_16
: Archives*size
as*16
. This is for small archive support.size_32
: Archives*size
as*32
(enabled by default)size_64
: Archives*size
as*64
. This is for large archive support.specialization
: Enables support for the unstable specialization feature for increased performance for a few specific casesstd
: 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
Crate support
Some common crates need to be supported by rkyv before an official integration has been made. Support is provided by rkyv for these crates, but in the future crates should depend on rkyv and provide their own implementations. The crates that already have support provided by rkyv should work toward integrating the implementations into themselves.
Crates supported by rkyv:
Examples
See Archive
for examples of how to use rkyv.
Re-exports
pub use util::*; | |
pub use validation::check_archived_root_with_context; | |
pub use validation::check_archived_value_with_context; | |
pub use validation::validators::check_archived_root; | |
pub use validation::validators::check_archived_value; |
Modules
boxed | An archived version of |
collections | Archived versions of standard library containers. |
de | Deserialization traits, deserializers, and adapters. |
ffi | Archived versions of FFI types. |
impls | Trait implementations for |
net | Archived versions of network types. |
option | An archived version of |
rc | Archived versions of shared pointers. |
rel_ptr | Relative pointer implementations and options. |
ser | Serialization traits, serializers, and adapters. |
string | Archived versions of string types. |
util | Utilities for common archive operations. |
validation | Validation implementations and helper types. |
vec | An archived version of |
with | Wrapper type support and commonly used wrappers. |
Macros
from_archived | Returns the unarchived value of the given archived primitive. |
out_field | Returns a tuple of the field offset and a mutable |
to_archived | Returns the archived value of the given archived primitive. |
Structs
Infallible | A fallible type that cannot produce errors |
Traits
Archive | A type that can be used without deserializing. |
ArchivePointee | An archived type with associated metadata for its relative pointer. |
ArchiveUnsized | A counterpart of |
Deserialize | Converts a type back from its archived form. |
DeserializeUnsized | A counterpart of |
Fallible | Contains the error type for traits with methods that can fail |
Serialize | Converts a type to its archived form. |
SerializeUnsized | A counterpart of |
Type Definitions
Archived | Alias for the archived version of some |
ArchivedMetadata | Alias for the archived metadata for some |
FixedIsize | The native type that |
FixedUsize | The native type that |
MetadataResolver | Alias for the metadata resolver for some |
RawRelPtr | The default raw relative pointer. |
RelPtr | The default relative pointer. |
Resolver | Alias for the resolver for some |
Derive Macros
Archive | Derives |
Deserialize | Derives |
Serialize | Derives |