versionize_derive 0.1.5

Implements the Versionize derive proc macro.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

**Versionize is a framework for version tolerant serializion/deserialization of
Rust data structures, designed for usecases that need fast deserialization 
times and minimal size overhead. It does not aim to be a generic serialization 
framework and only the [bincode](https://crates.io/crates/bincode) backend is 
supported.**

#### You may be looking for:
- [Versionize documentation](https://docs.rs/versionize/)
- [Releases](https://github.com/firecracker-microvm/versionize_derive/releases)

## Important note

This crate is currently used for cross-version serialization with the 
[Firecracker snapshot-restore dev preview][1], but has not been tested for 
other use cases. It should be considered **experimental software** outside the 
Firecracker context. It’s likely that this crate will see both interface and 
implementation changes in the future.

## Versionize in action

```rust
    extern crate versionize;
    extern crate versionize_derive;

    use versionize::{VersionMap, Versionize, VersionizeResult};
    use versionize_derive::Versionize;

    // The test structure is at version 3.
    #[derive(Debug, PartialEq, Versionize)]
    pub struct Test {
        a: u32,
        #[version(start = 2, end = 3)]
        b: u8,
        #[version(start = 3, default_fn = "default_c")]
        c: String,
    }

    impl Test {
        // Default value for field `c`.
        // The callback is invoked when deserialization from and older version
        // where the field did not exist.
        fn default_c(_source_version: u16) -> String {
            "test_string".to_owned()
        }
    }

    // Memory to hold the serialization output.
    let mut mem = vec![0u8; 512];
    // Create a new version map - it will start at version 1.
    let mut version_map = VersionMap::new();
    // Add new version and mark changes for Test struct: Set the current version
    // to point to Test struct version 2.
    version_map
        .new_version()
        .set_type_version(Test::type_id(), 2)
        .new_version()
        .set_type_version(Test::type_id(), 3);

    let test_struct = Test {
        a: 1337,
        b: 0xFF,
        c: "c_value".to_owned(),
    };

    // Serialize to version 2 - field c will not be serialized.
    test_struct
        .serialize(&mut mem.as_mut_slice(), &version_map, 2)
        .unwrap();

    // Deserialize from version 2 - c should contain the default_fn() return value.
    let restored_test_struct = Test::deserialize(&mut mem.as_slice(), &version_map, 2).unwrap();

    assert_eq!(
        restored_test_struct,
        Test {
            a: 1337,
            b: 255,
            c: "test_string".to_owned()
        }
    );
```

[1]: https://github.com/firecracker-microvm/firecracker/tree/v0.24.0