[][src]Trait rkyv::Archive

pub trait Archive {
    type Archived;
    type Resolver: Resolve<Self, Archived = Self::Archived>;
    fn archive<W: Write + ?Sized>(
        &self,
        writer: &mut W
    ) -> Result<Self::Resolver, W::Error>; }

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

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

Examples

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

use rkyv::{Aligned, Archive, ArchiveBuffer, Archived, WriteExt};

#[derive(Archive)]
struct Test {
    int: u8,
    string: String,
    option: Option<Vec<i32>>,
}

fn main() {
    let mut writer = ArchiveBuffer::new(Aligned([0u8; 256]));
    let value = Test {
        int: 42,
        string: "hello world".to_string(),
        option: Some(vec![1, 2, 3, 4]),
    };
    let pos = writer.archive(&value)
        .expect("failed to archive test");
    let buf = writer.into_inner();
    let archived = unsafe { &*buf.as_ref().as_ptr().add(pos).cast::<Archived<Test>>() };
    assert_eq!(archived.int, value.int);
    assert_eq!(archived.string, value.string);
    assert_eq!(archived.option, value.option);
}

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, but this example does everything to demonstrate how to implement Archive for your own types.

use core::{slice, str};
use rkyv::{
    Aligned,
    Archive,
    Archived,
    ArchiveBuffer,
    offset_of,
    RelPtr,
    Resolve,
    Write,
    WriteExt,
};

struct OwnedStr {
    inner: &'static str,
}

struct ArchivedOwnedStr {
    // This will be a relative pointer to the bytes of our string.
    ptr: RelPtr<u8>,
    // The length of the archived version must be explicitly sized
    // for 32/64-bit compatibility. Archive is not implemented for
    // usize and isize to help you avoid making this mistake.
    len: u32,
}

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
            // to its memory.
            let bytes = slice::from_raw_parts(self.ptr.as_ptr(), self.len as usize);
            str::from_utf8_unchecked(bytes)
        }
    }
}

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

impl Resolve<OwnedStr> for OwnedStrResolver {
    // This is essentially the output type of the resolver.
    // It must match the Archived associated type in our impl of
    // Archive for OwnedStr.
    type Archived = ArchivedOwnedStr;

    // The resolve function consumes the resolver and produces
    // the archived value at the given position.
    fn resolve(self, pos: usize, value: &OwnedStr) -> Self::Archived {
        Self::Archived {
            // We have to be careful to add the offset of the ptr
            // field, otherwise we'll be using the position of the
            // ArchivedOwnedStr instead of the position of the ptr.
            ptr: RelPtr::new(pos + offset_of!(ArchivedOwnedStr, ptr), self.bytes_pos),
            len: value.inner.len() as u32,
        }
    }
}

impl Archive for OwnedStr {
    type Archived = ArchivedOwnedStr;
    /// This is the resolver we'll return from archive.
    type Resolver = OwnedStrResolver;

    fn archive<W: Write + ?Sized>(&self, writer: &mut W) -> Result<Self::Resolver, W::Error> {
        // This is where we want to write the bytes of our string and
        // return a resolver that knows where those bytes were written.
        let bytes_pos = writer.pos();
        writer.write(self.inner.as_bytes())?;
        Ok(Self::Resolver { bytes_pos })
    }
}

fn main() {
    let mut writer = ArchiveBuffer::new(Aligned([0u8; 256]));
    const STR_VAL: &'static str = "I'm in an OwnedStr!";
    let value = OwnedStr { inner: STR_VAL };
    // It works!
    let pos = writer.archive(&value)
        .expect("failed to archive test");
    let buf = writer.into_inner();
    let archived = unsafe { &*buf.as_ref().as_ptr().add(pos).cast::<Archived<OwnedStr>>() };
    // Let's make sure our data got written correctly
    assert_eq!(archived.as_str(), STR_VAL);
}

Associated Types

type Archived

The archived version of this type.

type Resolver: Resolve<Self, Archived = Self::Archived>

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

Loading content...

Required methods

fn archive<W: Write + ?Sized>(
    &self,
    writer: &mut W
) -> Result<Self::Resolver, W::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.

Loading content...

Implementations on Foreign Types

impl Archive for () where
    (): Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for bool where
    bool: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for i8 where
    i8: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for i16 where
    i16: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for i32 where
    i32: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for i64 where
    i64: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for i128 where
    i128: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for u8 where
    u8: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for u16 where
    u16: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for u32 where
    u32: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for u64 where
    u64: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for u128 where
    u128: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for f32 where
    f32: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for f64 where
    f64: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl Archive for char where
    char: Copy
[src]

type Archived = Self

type Resolver = SelfResolver

impl<T11: Archive, T10: Archive, T9: Archive, T8: Archive, T7: Archive, T6: Archive, T5: Archive, T4: Archive, T3: Archive, T2: Archive, T1: Archive, T0: Archive> Archive for (T11, T10, T9, T8, T7, T6, T5, T4, T3, T2, T1, T0)[src]

type Archived = (T11::Archived, T10::Archived, T9::Archived, T8::Archived, T7::Archived, T6::Archived, T5::Archived, T4::Archived, T3::Archived, T2::Archived, T1::Archived, T0::Archived)

type Resolver = (T11::Resolver, T10::Resolver, T9::Resolver, T8::Resolver, T7::Resolver, T6::Resolver, T5::Resolver, T4::Resolver, T3::Resolver, T2::Resolver, T1::Resolver, T0::Resolver)

impl<T10: Archive, T9: Archive, T8: Archive, T7: Archive, T6: Archive, T5: Archive, T4: Archive, T3: Archive, T2: Archive, T1: Archive, T0: Archive> Archive for (T10, T9, T8, T7, T6, T5, T4, T3, T2, T1, T0)[src]

type Archived = (T10::Archived, T9::Archived, T8::Archived, T7::Archived, T6::Archived, T5::Archived, T4::Archived, T3::Archived, T2::Archived, T1::Archived, T0::Archived)

type Resolver = (T10::Resolver, T9::Resolver, T8::Resolver, T7::Resolver, T6::Resolver, T5::Resolver, T4::Resolver, T3::Resolver, T2::Resolver, T1::Resolver, T0::Resolver)

impl<T9: Archive, T8: Archive, T7: Archive, T6: Archive, T5: Archive, T4: Archive, T3: Archive, T2: Archive, T1: Archive, T0: Archive> Archive for (T9, T8, T7, T6, T5, T4, T3, T2, T1, T0)[src]

type Archived = (T9::Archived, T8::Archived, T7::Archived, T6::Archived, T5::Archived, T4::Archived, T3::Archived, T2::Archived, T1::Archived, T0::Archived)

type Resolver = (T9::Resolver, T8::Resolver, T7::Resolver, T6::Resolver, T5::Resolver, T4::Resolver, T3::Resolver, T2::Resolver, T1::Resolver, T0::Resolver)

impl<T8: Archive, T7: Archive, T6: Archive, T5: Archive, T4: Archive, T3: Archive, T2: Archive, T1: Archive, T0: Archive> Archive for (T8, T7, T6, T5, T4, T3, T2, T1, T0)[src]

type Archived = (T8::Archived, T7::Archived, T6::Archived, T5::Archived, T4::Archived, T3::Archived, T2::Archived, T1::Archived, T0::Archived)

type Resolver = (T8::Resolver, T7::Resolver, T6::Resolver, T5::Resolver, T4::Resolver, T3::Resolver, T2::Resolver, T1::Resolver, T0::Resolver)

impl<T7: Archive, T6: Archive, T5: Archive, T4: Archive, T3: Archive, T2: Archive, T1: Archive, T0: Archive> Archive for (T7, T6, T5, T4, T3, T2, T1, T0)[src]

type Archived = (T7::Archived, T6::Archived, T5::Archived, T4::Archived, T3::Archived, T2::Archived, T1::Archived, T0::Archived)

type Resolver = (T7::Resolver, T6::Resolver, T5::Resolver, T4::Resolver, T3::Resolver, T2::Resolver, T1::Resolver, T0::Resolver)

impl<T6: Archive, T5: Archive, T4: Archive, T3: Archive, T2: Archive, T1: Archive, T0: Archive> Archive for (T6, T5, T4, T3, T2, T1, T0)[src]

type Archived = (T6::Archived, T5::Archived, T4::Archived, T3::Archived, T2::Archived, T1::Archived, T0::Archived)

type Resolver = (T6::Resolver, T5::Resolver, T4::Resolver, T3::Resolver, T2::Resolver, T1::Resolver, T0::Resolver)

impl<T5: Archive, T4: Archive, T3: Archive, T2: Archive, T1: Archive, T0: Archive> Archive for (T5, T4, T3, T2, T1, T0)[src]

type Archived = (T5::Archived, T4::Archived, T3::Archived, T2::Archived, T1::Archived, T0::Archived)

type Resolver = (T5::Resolver, T4::Resolver, T3::Resolver, T2::Resolver, T1::Resolver, T0::Resolver)

impl<T4: Archive, T3: Archive, T2: Archive, T1: Archive, T0: Archive> Archive for (T4, T3, T2, T1, T0)[src]

type Archived = (T4::Archived, T3::Archived, T2::Archived, T1::Archived, T0::Archived)

type Resolver = (T4::Resolver, T3::Resolver, T2::Resolver, T1::Resolver, T0::Resolver)

impl<T3: Archive, T2: Archive, T1: Archive, T0: Archive> Archive for (T3, T2, T1, T0)[src]

type Archived = (T3::Archived, T2::Archived, T1::Archived, T0::Archived)

type Resolver = (T3::Resolver, T2::Resolver, T1::Resolver, T0::Resolver)

impl<T2: Archive, T1: Archive, T0: Archive> Archive for (T2, T1, T0)[src]

type Archived = (T2::Archived, T1::Archived, T0::Archived)

type Resolver = (T2::Resolver, T1::Resolver, T0::Resolver)

impl<T1: Archive, T0: Archive> Archive for (T1, T0)[src]

type Archived = (T1::Archived, T0::Archived)

type Resolver = (T1::Resolver, T0::Resolver)

impl<T0: Archive> Archive for (T0,)[src]

type Archived = (T0::Archived,)

type Resolver = (T0::Resolver,)

impl<T: Archive> Archive for [T; 31][src]

type Archived = [T::Archived; 31]

type Resolver = [T::Resolver; 31]

impl<T: Archive> Archive for [T; 30][src]

type Archived = [T::Archived; 30]

type Resolver = [T::Resolver; 30]

impl<T: Archive> Archive for [T; 29][src]

type Archived = [T::Archived; 29]

type Resolver = [T::Resolver; 29]

impl<T: Archive> Archive for [T; 28][src]

type Archived = [T::Archived; 28]

type Resolver = [T::Resolver; 28]

impl<T: Archive> Archive for [T; 27][src]

type Archived = [T::Archived; 27]

type Resolver = [T::Resolver; 27]

impl<T: Archive> Archive for [T; 26][src]

type Archived = [T::Archived; 26]

type Resolver = [T::Resolver; 26]

impl<T: Archive> Archive for [T; 25][src]

type Archived = [T::Archived; 25]

type Resolver = [T::Resolver; 25]

impl<T: Archive> Archive for [T; 24][src]

type Archived = [T::Archived; 24]

type Resolver = [T::Resolver; 24]

impl<T: Archive> Archive for [T; 23][src]

type Archived = [T::Archived; 23]

type Resolver = [T::Resolver; 23]

impl<T: Archive> Archive for [T; 22][src]

type Archived = [T::Archived; 22]

type Resolver = [T::Resolver; 22]

impl<T: Archive> Archive for [T; 21][src]

type Archived = [T::Archived; 21]

type Resolver = [T::Resolver; 21]

impl<T: Archive> Archive for [T; 20][src]

type Archived = [T::Archived; 20]

type Resolver = [T::Resolver; 20]

impl<T: Archive> Archive for [T; 19][src]

type Archived = [T::Archived; 19]

type Resolver = [T::Resolver; 19]

impl<T: Archive> Archive for [T; 18][src]

type Archived = [T::Archived; 18]

type Resolver = [T::Resolver; 18]

impl<T: Archive> Archive for [T; 17][src]

type Archived = [T::Archived; 17]

type Resolver = [T::Resolver; 17]

impl<T: Archive> Archive for [T; 16][src]

type Archived = [T::Archived; 16]

type Resolver = [T::Resolver; 16]

impl<T: Archive> Archive for [T; 15][src]

type Archived = [T::Archived; 15]

type Resolver = [T::Resolver; 15]

impl<T: Archive> Archive for [T; 14][src]

type Archived = [T::Archived; 14]

type Resolver = [T::Resolver; 14]

impl<T: Archive> Archive for [T; 13][src]

type Archived = [T::Archived; 13]

type Resolver = [T::Resolver; 13]

impl<T: Archive> Archive for [T; 12][src]

type Archived = [T::Archived; 12]

type Resolver = [T::Resolver; 12]

impl<T: Archive> Archive for [T; 11][src]

type Archived = [T::Archived; 11]

type Resolver = [T::Resolver; 11]

impl<T: Archive> Archive for [T; 10][src]

type Archived = [T::Archived; 10]

type Resolver = [T::Resolver; 10]

impl<T: Archive> Archive for [T; 9][src]

type Archived = [T::Archived; 9]

type Resolver = [T::Resolver; 9]

impl<T: Archive> Archive for [T; 8][src]

type Archived = [T::Archived; 8]

type Resolver = [T::Resolver; 8]

impl<T: Archive> Archive for [T; 7][src]

type Archived = [T::Archived; 7]

type Resolver = [T::Resolver; 7]

impl<T: Archive> Archive for [T; 6][src]

type Archived = [T::Archived; 6]

type Resolver = [T::Resolver; 6]

impl<T: Archive> Archive for [T; 5][src]

type Archived = [T::Archived; 5]

type Resolver = [T::Resolver; 5]

impl<T: Archive> Archive for [T; 4][src]

type Archived = [T::Archived; 4]

type Resolver = [T::Resolver; 4]

impl<T: Archive> Archive for [T; 3][src]

type Archived = [T::Archived; 3]

type Resolver = [T::Resolver; 3]

impl<T: Archive> Archive for [T; 2][src]

type Archived = [T::Archived; 2]

type Resolver = [T::Resolver; 2]

impl<T: Archive> Archive for [T; 1][src]

type Archived = [T::Archived; 1]

type Resolver = [T::Resolver; 1]

impl<T: Archive> Archive for [T; 0][src]

type Archived = [T::Archived; 0]

type Resolver = [T::Resolver; 0]

impl<T: Archive> Archive for Option<T>[src]

type Archived = ArchivedOption<T::Archived>

type Resolver = Option<T::Resolver>

impl<K: Archive + Hash + Eq, V: Archive> Archive for HashMap<K, V> where
    K::Archived: Hash + Eq
[src]

type Archived = ArchivedHashMap<K::Archived, V::Archived>

type Resolver = ArchivedHashMapResolver

impl<K: Archive + Hash + Eq> Archive for HashSet<K> where
    K::Archived: Hash + Eq
[src]

type Archived = ArchivedHashSet<K::Archived>

type Resolver = ArchivedHashSetResolver

impl Archive for String[src]

type Archived = ArchivedString

type Resolver = StringResolver

impl<T: ArchiveRef + ?Sized> Archive for Box<T>[src]

type Archived = ArchivedBox<Reference<T>>

type Resolver = BoxResolver<ReferenceResolver<T>>

impl<T: Archive> Archive for Vec<T>[src]

type Archived = ArchivedVec<Reference<[T]>>

type Resolver = VecResolver<ReferenceResolver<[T]>>

Loading content...

Implementors

Loading content...