epserde 0.13.1

ε-serde is an ε-copy (i.e., almost zero-copy) serialization/deserialization framework
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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

/*
 * SPDX-FileCopyrightText: 2023 Inria
 * SPDX-FileCopyrightText: 2023 Sebastiano Vigna
 *
 * SPDX-License-Identifier: Apache-2.0 OR MIT
 */

//! Helpers for serialization.

use super::{SerInner, WriteWithNames};
use crate::ser;
use crate::traits::*;

/// Checks that the type is [zero-copy at runtime], panicking otherwise.
///
/// # Panics
///
/// Panics if `V` is declared as zero-copy but its [`SerInner::IS_ZERO_COPY`]
/// constant is false.
///
/// [zero-copy at runtime]: SerInner::IS_ZERO_COPY
#[inline]
pub fn check_zero_copy<V: SerInner>() {
    if !V::IS_ZERO_COPY {
        panic!(
            "Cannot serialize type {} declared as zero-copy as it is not zero-copy",
            core::any::type_name::<V>()
        );
    }
}

/// Serialize a zero-copy structure checking [that the type is actually
/// zero-copy] and [aligning the stream beforehand].
///
/// This function makes the appropriate checks, writes the necessary padding and
/// then calls [`ser_zero_unchecked`].
///
/// # Safety
///
/// See the documentation of [`Serialize`].
///
/// [that the type is actually zero-copy]: SerInner::IS_ZERO_COPY
/// [aligning the stream beforehand]: WriteWithNames::align
/// [`Serialize`]: super::Serialize
#[inline]
pub unsafe fn ser_zero<V: ZeroCopy>(
    backend: &mut impl WriteWithNames,
    value: &V,
) -> ser::Result<()> {
    check_zero_copy::<V>();
    backend.align::<V>()?;
    unsafe { ser_zero_unchecked(backend, value) }
}

/// Serialize a zero-copy structure without checking [that the type is actually
/// zero-copy] and without [aligning the stream].
///
/// Note that this method uses a single [`write_all`] call to write the entire
/// structure.
///
/// # Safety
///
/// See the documentation of [`Serialize`].
///
/// [that the type is actually zero-copy]: SerInner::IS_ZERO_COPY
/// [aligning the stream]: WriteWithNames::align
/// [`write_all`]: super::WriteNoStd::write_all
/// [`Serialize`]: super::Serialize
#[inline]
pub unsafe fn ser_zero_unchecked<V: ZeroCopy>(
    backend: &mut impl WriteWithNames,
    value: &V,
) -> ser::Result<()> {
    // SAFETY: V is zero-copy, so its memory representation is a valid
    // sequence of bytes, except possibly for padding, whose bytes might be
    // uninitialized (this is why this function is unsafe).
    let buffer = unsafe {
        core::slice::from_raw_parts(value as *const V as *const u8, core::mem::size_of::<V>())
    };
    backend.write_bytes::<V>(buffer)
}

/// Serialize a slice of zero-copy structures by encoding its length first, and
/// then its bytes properly [aligned].
///
/// Note that this method uses a single `write_all`
/// call to write the entire slice.
///
/// Here we check [that the type is actually zero-copy].
///
/// # Safety
///
/// See the documentation of [`Serialize`].
///
/// [aligned]: WriteWithNames::align
/// [that the type is actually zero-copy]: SerInner::IS_ZERO_COPY
/// [`Serialize`]: super::Serialize
#[inline]
pub unsafe fn ser_slice_zero<V: ZeroCopy>(
    backend: &mut impl WriteWithNames,
    data: &[V],
) -> ser::Result<()> {
    check_zero_copy::<V>();

    let len = data.len();
    unsafe { backend.write("len", &len)? };
    let num_bytes = core::mem::size_of_val(data);
    // SAFETY: V is zero-copy, so the slice's memory representation is a valid
    // sequence of bytes, except possibly for padding, whose bytes might be
    // uninitialized (this is why this function is unsafe).
    let buffer = unsafe { core::slice::from_raw_parts(data.as_ptr() as *const u8, num_bytes) };
    backend.align::<V>()?;
    backend.write_bytes::<V>(buffer)
}

/// Serialize a slice of deep-copy structures by encoding
/// its length first, and then the contents item by item.
///
/// # Safety
///
/// See the documentation of [`Serialize`].
///
/// [`Serialize`]: super::Serialize
#[inline]
pub unsafe fn ser_slice_deep<V: SerInner>(
    backend: &mut impl WriteWithNames,
    data: &[V],
) -> ser::Result<()> {
    let len = data.len();
    unsafe {
        backend.write("len", &len)?;
        for item in data.iter() {
            backend.write("item", item)?;
        }
    }
    Ok(())
}