cursor-api/patch/rkyv-0.8.12

rkyv (archive) is a zero-copy deserialization framework for Rust

Resources

Learning Materials

• The rkyv book covers the motivation, architecture, and major features of rkyv
• The rkyv discord is a great place to get help with specific issues and meet other people using rkyv

Documentation

• rkyv, the core library
• rkyv_dyn, which adds trait object support to rkyv

Benchmarks

• The rust serialization benchmark is a shootout style benchmark comparing many rust serialization solutions. It includes special benchmarks for zero-copy serialization solutions like rkyv.

Sister Crates

• rend, which rkyv uses for endian-agnostic features
• bytecheck, which rkyv uses for validation
• rancor, which rkyv uses for error handling
• ptr_meta, which rkyv uses for pointer manipulation

Example

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 (enabled by default) Read more about available features.

Thanks

Thanks to all the sponsors that keep development sustainable.