reallyme-buffa 0.1.0

ReallyMe fork: A pure Rust Protocol Buffers implementation with first-class editions support
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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
// Modified by ReallyMe Technologies Limited.
//! Map fields: `map<K, V>` stored as a [`MapStorage`] collection.
//!
//! A map is written as one length-delimited record per entry, each holding
//! the key as field 1 and the value as field 2. The interpreters treat the
//! key and the value as two fields of a message with two entries and reach
//! them through pointers to the collection's storage, so every key and value
//! kind is handled by the arms that handle it as an ordinary field. Only
//! what depends on the collection's type is generic: iterating it, and
//! inserting an entry that has been decoded into locals.
//!
//! # Why the loops test for a map
//!
//! The dispatch functions `size_kind`, `write_kind` and `merge_kind` have an
//! arm for every kind, and the arm for [`Kind::Map`] is `unreachable!`.
//! `compute_size`, `write_message` and `merge_one` (which `merge_slice` calls
//! for each field) test for a map first and call [`size_map`], [`write_map`]
//! or `merge_map` themselves. `merge_kind` is also called by `merge_entry`,
//! for a key and a value, which are never maps.
//!
//! Calling the map interpreters from the arms made the dispatch functions
//! large enough that, at `opt-level = 3`, the compiler stopped inlining them
//! into the loops and called them once per field. With fat LTO, one codegen
//! unit and Rust 1.95, the `whatsapp.proto` of `waproto` was 4% larger at
//! `opt-level = 3`, and a schema of table messages without maps 2.6% larger;
//! at `opt-level = "z"` the two layouts were within 0.1% of each other. This
//! is an inlining threshold, so it depends on the compiler and the size of the
//! dispatch functions, and any change to them or a new toolchain can bring it
//! back. To check, build a schema of table messages without maps at
//! `opt-level = 3` (fat LTO, one codegen unit) and compare the binary's size
//! with a build before a change to the dispatch functions: a jump of a few
//! percent is this.

use super::decode::{merge_kind, take_len_delimited};
use super::encode::{put_tag, write_kind};
use super::shape::{DirectMsgVt, EnumVtOf};
use super::size::size_kind;
use super::{Aux, Entry, EnumShape, Kind, KindSlot, MessageTable, IMPLICIT, NO_UNKNOWN, REQUIRED};
use crate::encoding::{check_wire_type, encode_varint, varint_len, Tag, WireType};
use crate::map_codec::MapStorage;
use crate::{
    types, DecodeContext, DecodeError, EncodeSink, SizeCache, UnknownField, UnknownFieldData,
    UnknownFields,
};

/// Descriptor of a map field: the kinds of its key and value, and functions
/// that iterate the collection and insert a decoded entry, instantiated for
/// its type.
pub struct MapVt {
    /// The key (field 1) and the value (field 2), as the entries of a message
    /// whose fields are reached by pointer, so their offsets are unused.
    entries: [Entry; 2],
    /// The descriptor of the value, if its kind has one, which its entry
    /// indexes at 0.
    value_aux: Option<Aux>,
    /// The size in bytes of a key and a value together, which an entry read
    /// from the wire counts towards the element-memory limit.
    footprint: usize,
    /// Call the function with a pointer to each key and its value.
    ///
    /// # Safety
    ///
    /// The first argument points to a live collection of the type the
    /// descriptor was built for, which nothing mutates during the call.
    for_each: unsafe fn(*const u8, &mut dyn FnMut(*const u8, *const u8)),
    /// Create a key and a value with their defaults, pass pointers to them to
    /// the function, and insert them into the collection if it returns
    /// `true`. Returns what the function returned.
    ///
    /// # Safety
    ///
    /// The first argument points to a live collection of the type the
    /// descriptor was built for, to which the caller has exclusive access for
    /// the whole call, as a `&mut` would give it: nothing else reads or
    /// writes the collection while it runs, including through the function.
    decode_entry: unsafe fn(*mut u8, &mut EntryReader<'_>) -> Result<bool, DecodeError>,
}

/// Reads the key and value of one entry through pointers to them and returns
/// whether to insert the entry.
type EntryReader<'a> = dyn FnMut(*mut u8, *mut u8) -> Result<bool, DecodeError> + 'a;

#[cfg(all(test, feature = "zeroize"))]
mod cleanup_tests {
    use super::*;
    use alloc::collections::BTreeMap;
    use core::sync::atomic::{AtomicUsize, Ordering};

    static KEYS: AtomicUsize = AtomicUsize::new(0);
    static VALUES: AtomicUsize = AtomicUsize::new(0);
    #[derive(Default)]
    struct Map(BTreeMap<u32, u64>);
    impl MapStorage for Map {
        type Key = u32;
        type Value = u64;
        fn storage_len(&self) -> usize {
            self.0.len()
        }
        fn storage_clear(&mut self) {
            self.0.clear();
        }
        fn storage_insert(&mut self, key: u32, value: u64) {
            self.0.insert(key, value);
        }
        fn storage_erase_key(key: &mut u32) {
            assert_eq!(*key, 7);
            *key = 0;
            KEYS.fetch_add(1, Ordering::SeqCst);
        }
        fn storage_erase_value(value: &mut u64) {
            assert_eq!(*value, 37);
            *value = 0;
            VALUES.fetch_add(1, Ordering::SeqCst);
        }
        fn storage_iter<'a>(&'a self) -> impl Iterator<Item = (&'a u32, &'a u64)>
        where
            Self::Key: 'a,
            Self::Value: 'a,
        {
            self.0.iter()
        }
    }
    #[test]
    fn manual_table_map_slots_follow_the_destination_cleanup_policy() {
        KEYS.store(0, Ordering::SeqCst);
        VALUES.store(0, Ordering::SeqCst);
        let mut map = Map::default();
        for outcome in 0..3 {
            let mut read = |key: *mut u8, value: *mut u8| {
                // SAFETY: decode_entry_impl supplies exclusively borrowed,
                // initialized u32/u64 slots for this exact MapStorage type.
                unsafe {
                    *key.cast::<u32>() = 7;
                    *value.cast::<u64>() = 37;
                }
                if outcome == 0 {
                    Err(DecodeError::UnexpectedEof)
                } else {
                    Ok(outcome == 2)
                }
            };
            // SAFETY: the pointer names a live Map with exclusive access
            // throughout the callback; its entry types match the callback.
            let result =
                unsafe { decode_entry_impl::<Map>((&mut map as *mut Map).cast(), &mut read) };
            match outcome {
                0 => assert_eq!(result, Err(DecodeError::UnexpectedEof)),
                1 => assert_eq!(result, Ok(false)),
                _ => assert_eq!(result, Ok(true)),
            }
            let erased = if outcome == 0 { 1 } else { 2 };
            assert_eq!(KEYS.load(Ordering::SeqCst), erased);
            assert_eq!(VALUES.load(Ordering::SeqCst), erased);
        }
        assert_eq!(map.0.get(&7), Some(&37));
    }
}

/// # Safety
///
/// `map` points to a live `Mp`, which nothing mutates during the call.
unsafe fn for_each_impl<Mp: MapStorage>(map: *const u8, f: &mut dyn FnMut(*const u8, *const u8)) {
    // SAFETY: the caller passes a pointer to a live `Mp`.
    let map = unsafe { &*map.cast::<Mp>() };
    for (key, value) in map.storage_iter() {
        f(
            (key as *const Mp::Key).cast(),
            (value as *const Mp::Value).cast(),
        );
    }
}

/// # Safety
///
/// `map` points to a live `Mp` to which the caller has exclusive access for
/// the call.
unsafe fn decode_entry_impl<Mp: MapStorage>(
    map: *mut u8,
    f: &mut EntryReader<'_>,
) -> Result<bool, DecodeError>
where
    Mp::Key: Default,
    Mp::Value: Default,
{
    let mut key = crate::erasing::Erasing::new(Mp::Key::default(), Mp::storage_erase_key);
    let mut value = crate::erasing::Erasing::new(Mp::Value::default(), Mp::storage_erase_value);
    let keep = f(
        (&mut *key as *mut Mp::Key).cast(),
        (&mut *value as *mut Mp::Value).cast(),
    )?;
    if keep {
        // SAFETY: the caller passes a pointer to a live `Mp` that it has
        // exclusive access to.
        unsafe { (*map.cast::<Mp>()).storage_insert(key.into_inner(), value.into_inner()) };
    }
    Ok(keep)
}

impl MapVt {
    /// Describe a map of type `Mp` whose keys are of the kind `KK` names and
    /// whose values are of the string, bytes or scalar kind `VK` names.
    ///
    /// # Panics
    ///
    /// Panics, at compile time when used to initialise a `static`, if `KK` or
    /// `VK` does not have required cardinality (`Int32Required`, not
    /// `Int32Optional` or `Int32Repeated`). The key is not restricted to the
    /// types protobuf allows for one (integers, `bool` and `string`): any
    /// scalar, string or bytes kind with required cardinality is accepted, and
    /// the collection type decides whether it can be keyed by that type.
    #[must_use]
    pub const fn new<Mp, KK, VK>() -> Self
    where
        KK: KindSlot,
        VK: KindSlot,
        Mp: MapStorage<Key = KK::Slot, Value = VK::Slot>,
        KK::Slot: Default,
        VK::Slot: Default,
    {
        Self::build::<Mp>(KK::KIND, VK::KIND, None)
    }

    /// Describe a map of type `Mp` whose keys are of the kind `KK` names and
    /// whose values are enums stored as `S`, which must have implicit
    /// presence: [`ImplicitOpen`](super::ImplicitOpen) or
    /// [`ImplicitClosed`](super::ImplicitClosed).
    ///
    /// A value that a closed enum does not know makes the whole entry
    /// unknown, as in unrolled code.
    ///
    /// # Panics
    ///
    /// As for [`new`](Self::new), and if `S` is not an implicit shape.
    #[must_use]
    pub const fn with_enum<Mp, KK, S>() -> Self
    where
        KK: KindSlot,
        S: EnumShape,
        Mp: MapStorage<Key = KK::Slot, Value = S::Slot>,
        KK::Slot: Default,
        S::Slot: Default,
    {
        assert!(
            S::CARD == IMPLICIT,
            "buffa table: a map's enum values must have an implicit shape"
        );
        Self::build::<Mp>(
            KK::KIND,
            Kind::EnumRequired,
            Some(Aux::Enum(&EnumVtOf::<S>::VT)),
        )
    }

    /// Describe a map of type `Mp` whose keys are of the kind `KK` names and
    /// whose values are messages of type `M`, which `vt` describes: a
    /// [`DirectMsgVt::new`] for a message that has a table, or
    /// [`DirectMsgVt::via_message`] for one that has not, which is reached
    /// through its [`Message`](crate::Message) impl. Its type ties `vt` to the
    /// map's value type, so a descriptor of another message is a type error:
    ///
    /// ```
    /// use buffa::table::{kinds, DirectMsgVt, MapVt, Table};
    /// use std::collections::BTreeMap;
    ///
    /// #[derive(Default)]
    /// struct Point {
    ///     x: i32,
    /// }
    /// static POINT: Table<Point> = buffa::__table!(
    ///     Point,
    ///     abi = buffa::table::ABI,
    ///     entries = [buffa::__table_entry!(Point, x, Int32Implicit, 1)],
    ///     dense = &[0, 1],
    ///     aux = [],
    ///     unknown = none,
    /// );
    /// static VT: DirectMsgVt<Point> = DirectMsgVt::new(&POINT);
    /// let _ = MapVt::with_msg::<BTreeMap<String, Point>, kinds::StrRequired, Point>(&VT);
    /// ```
    ///
    /// ```compile_fail,E0308
    /// use buffa::table::{kinds, DirectMsgVt, MapVt, Table};
    /// use std::collections::BTreeMap;
    ///
    /// #[derive(Default)]
    /// struct Point {
    ///     x: i32,
    /// }
    /// #[derive(Default)]
    /// struct Other;
    /// static POINT: Table<Point> = buffa::__table!(
    ///     Point,
    ///     abi = buffa::table::ABI,
    ///     entries = [buffa::__table_entry!(Point, x, Int32Implicit, 1)],
    ///     dense = &[0, 1],
    ///     aux = [],
    ///     unknown = none,
    /// );
    /// static VT: DirectMsgVt<Point> = DirectMsgVt::new(&POINT);
    /// // The values are `Other`s, but the descriptor is a `Point`'s.
    /// let _ = MapVt::with_msg::<BTreeMap<String, Other>, kinds::StrRequired, Other>(&VT);
    /// ```
    ///
    /// # Panics
    ///
    /// As for [`new`](Self::new).
    #[must_use]
    pub const fn with_msg<Mp, KK, M>(vt: &'static DirectMsgVt<M>) -> Self
    where
        KK: KindSlot,
        Mp: MapStorage<Key = KK::Slot, Value = M>,
        KK::Slot: Default,
        M: Default,
    {
        Self::build::<Mp>(KK::KIND, Kind::MsgSingular, Some(Aux::Msg(&vt.vt)))
    }

    const fn build<Mp: MapStorage>(key: Kind, value: Kind, value_aux: Option<Aux>) -> Self
    where
        Mp::Key: Default,
        Mp::Value: Default,
    {
        assert!(
            key.card() == REQUIRED,
            "buffa table: a map key must be of a required scalar or string kind"
        );
        assert!(
            value as u8 == Kind::MsgSingular as u8 || value.card() == REQUIRED,
            "buffa table: a map value must be of a required kind or a singular message"
        );
        Self {
            entries: [Entry::new(key, 1, 0, 0), Entry::new(value, 2, 0, 0)],
            value_aux,
            footprint: core::mem::size_of::<Mp::Key>() + core::mem::size_of::<Mp::Value>(),
            for_each: for_each_impl::<Mp>,
            decode_entry: decode_entry_impl::<Mp>,
        }
    }

    /// The key and value as a two-field message, for the interpreters.
    #[inline]
    fn entry_table(&'static self) -> MessageTable {
        MessageTable {
            entries: &self.entries,
            dense: &[],
            aux: match &self.value_aux {
                Some(aux) => core::slice::from_ref(aux),
                None => &[],
            },
            unknown: NO_UNKNOWN,
        }
    }
}

/// The encoded size of the map at `slot`, whose field is `e`, recording the
/// sizes of message values in `cache`.
///
/// # Safety
///
/// `slot` points to the map field `e` describes.
#[inline(never)]
pub(super) unsafe fn size_map(
    table: &MessageTable,
    e: &Entry,
    slot: *const u8,
    cache: &mut SizeCache,
) -> u64 {
    let tl = u64::from(e.tag_len);
    let vt = table.map_vt(e);
    let entry_table = vt.entry_table();
    let mut size = 0u64;
    // SAFETY: the descriptor was built for the slot's type, and the entry
    // table describes what it passes to the closure.
    unsafe {
        (vt.for_each)(slot, &mut |key, value| {
            let entry = size_kind(&entry_table, &vt.entries[0], key, cache)
                + size_kind(&entry_table, &vt.entries[1], value, cache);
            size += tl + varint_len(entry) as u64 + entry;
        });
    }
    size
}

/// Write the map at `slot`, whose field is `e`, taking the sizes of message
/// values from `cache` in the order `size_map` recorded them.
///
/// # Safety
///
/// As for [`size_map`].
#[inline(never)]
pub(super) unsafe fn write_map<K: EncodeSink>(
    table: &MessageTable,
    e: &Entry,
    slot: *const u8,
    cache: &mut SizeCache,
    buf: &mut K,
) {
    let vt = table.map_vt(e);
    let entry_table = vt.entry_table();
    let [key_entry, value_entry] = &vt.entries;
    // SAFETY: as for `size_map`.
    unsafe {
        (vt.for_each)(slot, &mut |key, value| {
            let key_len = size_kind(&entry_table, key_entry, key, cache);
            if value_entry.kind == Kind::MsgSingular {
                // The size pass recorded the value's size, and the value's own
                // write takes the sizes of what it holds after it.
                let len = cache.consume_next();
                let inner = u64::from(len);
                let entry =
                    key_len + u64::from(value_entry.tag_len) + varint_len(inner) as u64 + inner;
                put_tag(e, buf);
                encode_varint(entry, buf);
                write_kind(&entry_table, key_entry, key, cache, buf);
                put_tag(value_entry, buf);
                encode_varint(inner, buf);
                let msg = entry_table.msg_vt(value_entry);
                msg.child.write_to((msg.get)(value), len, cache, buf);
            } else {
                let entry = key_len + size_kind(&entry_table, value_entry, value, cache);
                put_tag(e, buf);
                encode_varint(entry, buf);
                write_kind(&entry_table, key_entry, key, cache, buf);
                write_kind(&entry_table, value_entry, value, cache, buf);
            }
        });
    }
}

/// Decode one entry of the map at `slot`, whose field is `e`, from the front
/// of `buf`, after its `tag`.
///
/// An entry whose value is a closed enum's unknown number is dropped, or kept
/// whole as an unknown field of the message at `base` if it keeps any.
///
/// # Safety
///
/// `slot` points to the map field `e` describes, inside the live message at
/// `base` of the type `table` describes.
#[inline(never)]
pub(super) unsafe fn merge_map(
    table: &MessageTable,
    e: &Entry,
    base: *mut u8,
    slot: *mut u8,
    tag: Tag,
    buf: &mut &[u8],
    ctx: DecodeContext<'_>,
) -> Result<(), DecodeError> {
    check_wire_type(tag, WireType::LengthDelimited)?;
    let vt = table.map_vt(e);
    let payload = take_len_delimited(buf)?;
    // An entry amplifies as a repeated element does: an omitted message value
    // still materialises a whole value in the map, and a few bytes of key buy
    // a slot. Count both before decoding either.
    ctx.register_element_memory(vt.footprint)?;
    let entry_table = vt.entry_table();
    // SAFETY: the descriptor was built for the slot's type, and the entry
    // table describes what it passes to the closure.
    let inserted = unsafe {
        (vt.decode_entry)(slot, &mut |key, value| {
            merge_entry(&entry_table, key, value, payload, ctx)
        })?
    };
    if !inserted && table.unknown != NO_UNKNOWN {
        ctx.register_unknown_field()?;
        // SAFETY: `unknown` is the offset of the message's `UnknownFields`.
        unsafe {
            (*base.add(table.unknown as usize).cast::<UnknownFields>()).push(UnknownField {
                number: e.tag >> 3,
                data: UnknownFieldData::LengthDelimited(payload.to_vec()),
            });
        }
    }
    Ok(())
}

/// Decode the fields of one entry, `payload`, into the key at `key` and the
/// value at `value`. Returns `false` if the last occurrence of the value is
/// an enum number that a closed enum does not know.
///
/// # Safety
///
/// `key` and `value` point to live values of the types the two entries of
/// `table`, the entry table of a map's descriptor, describe.
unsafe fn merge_entry(
    table: &MessageTable,
    key: *mut u8,
    value: *mut u8,
    mut payload: &[u8],
    ctx: DecodeContext<'_>,
) -> Result<bool, DecodeError> {
    let [key_entry, value_entry] = table.entries else {
        unreachable!("an entry table has a key and a value")
    };
    let mut known = true;
    while !payload.is_empty() {
        let tag = Tag::decode(&mut payload)?;
        match tag.field_number() {
            1 => {
                // SAFETY: `key` points to the value the key entry describes,
                // and the entry table has no unknown fields, so `merge_kind`
                // does not read the base pointer.
                unsafe {
                    merge_kind(
                        table,
                        key_entry,
                        core::ptr::null_mut(),
                        key,
                        tag,
                        &mut payload,
                        ctx,
                    )
                }?;
            }
            2 if value_entry.kind == Kind::EnumRequired => {
                check_wire_type(tag, WireType::Varint)?;
                let raw = types::decode_int32(&mut payload)?;
                // SAFETY: `value` points to the enum the value entry's
                // descriptor was built for.
                known = unsafe { (table.enum_vt(value_entry).set)(value, raw) };
                if !known {
                    ctx.check_unknown_field()?;
                }
            }
            2 => {
                // SAFETY: as for the key.
                unsafe {
                    merge_kind(
                        table,
                        value_entry,
                        core::ptr::null_mut(),
                        value,
                        tag,
                        &mut payload,
                        ctx,
                    )
                }?;
            }
            _ => crate::encoding::skip_unknown_field(tag, &mut payload, ctx)?,
        }
    }
    Ok(known)
}