Trait Archive

Source

pub trait Archive {
    type Archived: Portable;
    type Resolver;

    const COPY_OPTIMIZATION: CopyOptimization<Self> = _;

    // Required method
    fn resolve(&self, resolver: Self::Resolver, out: Place<Self::Archived>);
}

Expand description

A type that can be used without deserializing.

Archive is one of three basic traits used to work with zero-copy data and controls the layout of the data in its archived zero-copy representation. The Serialize trait helps transform types into that representation, and the Deserialize trait helps transform types back out.

Types that implement Archive must have a well-defined archived size. Unsized types can be supported using the ArchiveUnsized trait, along with SerializeUnsized and DeserializeUnsized.

Archiving is done depth-first, writing any data owned by a type before writing the data for the type itself. The type must be able to create the archived type from only its own data and its resolver.

Archived data is always treated as if it is tree-shaped, with the root owning its direct descendents and so on. Data that is not tree-shaped can be supported using special serializer and deserializer bounds (see ArchivedRc for example). In a buffer of serialized data, objects are laid out in reverse order. This means that the root object is located near the end of the buffer and leaf objects are located near the beginning.

§Examples

Most of the time, #[derive(Archive)] will create an acceptable implementation. You can use the #[rkyv(...)] attribute to control how the implementation is generated. See the Archive derive macro for more details.

use rkyv::{deserialize, rancor::Error, Archive, Deserialize, Serialize};

#[derive(Archive, Deserialize, Serialize, Debug, PartialEq)]
#[rkyv(
    // This will generate a PartialEq impl between our unarchived
    // and archived types
    compare(PartialEq),
    // Derives can be passed through to the generated type:
    derive(Debug),
)]
struct Test {
    int: u8,
    string: String,
    option: Option<Vec<i32>>,
}

fn main() {
    let value = Test {
        int: 42,
        string: "hello world".to_string(),
        option: Some(vec![1, 2, 3, 4]),
    };

    // Serializing is as easy as a single function call
    let _bytes = rkyv::to_bytes::<Error>(&value).unwrap();

    // Or you can customize your serialization for better performance or control
    // over resource usage
    use rkyv::{api::high::to_bytes_with_alloc, ser::allocator::Arena};

    let mut arena = Arena::new();
    let bytes =
        to_bytes_with_alloc::<_, Error>(&value, arena.acquire()).unwrap();

    // You can use the safe API for fast zero-copy deserialization
    let archived = rkyv::access::<ArchivedTest, Error>(&bytes[..]).unwrap();
    assert_eq!(archived, &value);

    // Or you can use the unsafe API for maximum performance
    let archived =
        unsafe { rkyv::access_unchecked::<ArchivedTest>(&bytes[..]) };
    assert_eq!(archived, &value);

    // And you can always deserialize back to the original type
    let deserialized = deserialize::<Test, Error>(archived).unwrap();
    assert_eq!(deserialized, value);
}

Note: the safe API requires the bytecheck feature.

Many of the core and standard library types already have Archive implementations available, but you may need to implement Archive for your own types in some cases the derive macro cannot handle.

In this example, we add our own wrapper that serializes a &'static str as if it’s owned. Normally you can lean on the archived version of String to do most of the work, or use the Inline to do exactly this. This example does everything to demonstrate how to implement Archive for your own types.

use core::{slice, str};

use rkyv::{
    access_unchecked,
    rancor::{Error, Fallible},
    ser::Writer,
    to_bytes,
    Archive, ArchiveUnsized, Archived, Portable, RelPtr, Serialize,
    SerializeUnsized, munge::munge, Place,
};

struct OwnedStr {
    inner: &'static str,
}

#[derive(Portable)]
#[repr(transparent)]
struct ArchivedOwnedStr {
    // This will be a relative pointer to our string
    ptr: RelPtr<str>,
}

impl ArchivedOwnedStr {
    // This will help us get the bytes of our type as a str again.
    fn as_str(&self) -> &str {
        unsafe {
            // The as_ptr() function of RelPtr will get a pointer the str
            &*self.ptr.as_ptr()
        }
    }
}

struct OwnedStrResolver {
    // This will be the position that the bytes of our string are stored at.
    // We'll use this to resolve the relative pointer of our
    // ArchivedOwnedStr.
    pos: usize,
}

// The Archive implementation defines the archived version of our type and
// determines how to turn the resolver into the archived form. The Serialize
// implementations determine how to make a resolver from the original value.
impl Archive for OwnedStr {
    type Archived = ArchivedOwnedStr;
    // This is the resolver we can create our Archived version from.
    type Resolver = OwnedStrResolver;

    // The resolve function consumes the resolver and produces the archived
    // value at the given position.
    fn resolve(
        &self,
        resolver: Self::Resolver,
        out: Place<Self::Archived>,
    ) {
        munge!(let ArchivedOwnedStr { ptr } = out);
        RelPtr::emplace_unsized(
            resolver.pos,
            self.inner.archived_metadata(),
            ptr,
        );
    }
}

// We restrict our serializer types with Writer because we need its
// capabilities to serialize the inner string. For other types, we might
// need more or less restrictive bounds on the type of S.
impl<S: Fallible + Writer + ?Sized> Serialize<S> for OwnedStr {
    fn serialize(
        &self,
        serializer: &mut S,
    ) -> Result<Self::Resolver, S::Error> {
        // This is where we want to write the bytes of our string and return
        // a resolver that knows where those bytes were written.
        // We also need to serialize the metadata for our str.
        Ok(OwnedStrResolver {
            pos: self.inner.serialize_unsized(serializer)?,
        })
    }
}

const STR_VAL: &'static str = "I'm in an OwnedStr!";
let value = OwnedStr { inner: STR_VAL };
// It works!
let buf = to_bytes::<Error>(&value).expect("failed to serialize");
let archived =
    unsafe { access_unchecked::<ArchivedOwnedStr>(buf.as_ref()) };
// Let's make sure our data got written correctly
assert_eq!(archived.as_str(), STR_VAL);

Provided Associated Constants§

Source

const COPY_OPTIMIZATION: CopyOptimization<Self> = _

An optimization flag that allows the bytes of this type to be copied directly to a writer instead of calling serialize.

This optimization is disabled by default. To enable this optimization, you must unsafely attest that Self is trivially copyable using CopyOptimization::enable or CopyOptimization::enable_if.

Required Associated Types§

Source

type Archived: Portable

The archived representation of this type.

In this form, the data can be used with zero-copy deserialization.

Source

type Resolver

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

Required Methods§

Source

fn resolve(&self, resolver: Self::Resolver, out: Place<Self::Archived>)

Creates the archived version of this value at the given position and writes it to the given output.

The output should be initialized field-by-field rather than by writing a whole struct. Performing a typed copy will mark all of the padding bytes as uninitialized, but they must remain set to the value they currently have. This prevents leaking uninitialized memory to the final archive.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Trait ArchiveCopy item path

§Examples

Provided Associated Constants§

const COPY_OPTIMIZATION: CopyOptimization<Self> = _

Required Associated Types§

type Archived: Portable

type Resolver

Required Methods§

fn resolve(&self, resolver: Self::Resolver, out: Place<Self::Archived>)

Dyn Compatibility§

Implementations on Foreign Types§

impl Archive for IpAddr

type Archived = ArchivedIpAddr

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for SocketAddr

type Archived = ArchivedSocketAddr

type Resolver = ()

fn resolve(&self, resolver: Self::Resolver, out: Place<Self::Archived>)

impl Archive for bool

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = bool

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for char

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = char_le

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for f32

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = f32_le

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for f64

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = f64_le

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for i8

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = i8

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for i16

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = i16_le

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for i32

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = i32_le

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for i64

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = i64_le

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for i128

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = i128_le

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for isize

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = i32_le

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for u8

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = u8

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for u16

const COPY_OPTIMIZATION: CopyOptimization<Self>

type Archived = u16_le

type Resolver = ()

fn resolve(&self, _: Self::Resolver, out: Place<Self::Archived>)

impl Archive for u32

Trait Archive