[][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 is based off of the standard library's hashbrown crate and should have nearly identical performance.

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-limited applications.

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 implementations for some traits and provides an Archive implementation for slices with elements that implement ArchiveSelf. Ideal for #[no_std] environments.
  • inline_more: Performs more aggressive function inlining.
  • more_portable: Avoids using sse2-optimized intrinsics since they may cause alignment issues across machines. This feature may go away once any portability bugs are identified and fixed.
  • nightly: Enables some nightly features, such as likely.
  • specialization: Enables the unfinished specialization feature and provides more efficient implementations of some functions when working with ArchiveSelf types.
  • std: Enables standard library support.

By default, the std and inline_more features are enabled.

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 io::Write and equips it with Write.

RelPtr

A strongly typed pointer which resolves to relative to its position in memory.

SelfResolver

A resolver that always resolves to the unarchived value. This can be useful while implementing ArchiveSelf.

Enums

ArchiveBufferError

The error type returned by an ArchiveBuffer.

Traits

Archive

Writes a type to a Writer) so it can be used without deserializing.

ArchiveRef

This trait is a counterpart of Archive that's suitable for unsized types. Instead of archiving its value directly, ArchiveRef archives a type that dereferences to its archived type. As a consequence, its Resolver resolves to a Reference instead of the archived type.

ArchiveSelf

A trait that indicates that some Archive type can be copied directly to an archive without additional processing.

Resolve

Creates an archived value when given a value and position.

Write

A #[no_std] compliant writer that knows where it is.

WriteExt

Helper functions on Write objects.

Type Definitions

Archived

Alias for the archived version of some Archive type.

Reference

Alias for the reference for some ArchiveRef type.

ReferenceResolver

Alias for the resolver of the reference for some ArchiveRef type.

Resolver

Alias for the resolver for some Archive type.

Derive Macros

Archive

Derives Archive for the labeled type.