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