Merge remote-tracking branch 'origin/main' into danlaine/contiguous-2

Author: danlaine

Cargo.lock

@@ -114,6 +114,7 @@ crc = "3.4.0"
 crc-fast = { version = "1.10.0", default-features = false }
 criterion = "0.7.0"
 crossbeam-queue = "0.3.12"
+crossbeam-utils = "0.8.21"
 crossterm = "0.29.0"
 ctutils = "0.3.1"
 curve25519-dalek = "4.1.3"

Cargo.toml

@@ -1,7 +1,11 @@
 //! Core traits for encoding and decoding.
 
 use crate::error::Error;
+#[cfg(not(feature = "std"))]
+use alloc::vec::Vec;
 use bytes::{Buf, BufMut, Bytes, BytesMut};
+#[cfg(feature = "std")]
+use std::vec::Vec;
 
 /// Trait for types with a known, fixed encoded size.
 ///
@@ -23,20 +27,86 @@ pub trait EncodeSize {
     /// Returns the encoded size of this value (in bytes).
     fn encode_size(&self) -> usize;
 
+    /// Returns the total encoded size of a sequence, excluding any container-specific length
+    /// prefix.
+    ///
+    /// Container implementations call this hook so element types can provide a more efficient
+    /// aggregate size calculation. The default preserves normal element-by-element sizing.
+    /// Fixed-size implementations compute `SIZE * len`, which avoids an O(n) sizing prepass
+    /// before containers such as `Vec<T>` allocate their output buffer.
+    ///
+    /// This hook exists because stable Rust cannot express the overlapping specialized
+    /// container impls that would otherwise provide this aggregate path directly.
+    ///
+    /// This is hidden from generated documentation because it is an implementation hook for
+    /// codec's container types, not part of the intended user-facing API. Most users should
+    /// implement [EncodeSize::encode_size] or [FixedSize] instead.
+    #[doc(hidden)]
+    #[inline]
+    fn encode_size_slice(values: &[Self]) -> usize
+    where
+        Self: Sized,
+    {
+        values.iter().map(EncodeSize::encode_size).sum()
+    }
+
     /// Returns the encoded size excluding bytes passed to [`BufsMut::push`]
     /// during [`Write::write_bufs`]. Used to size the working buffer for inline
     /// writes. Override alongside [`Write::write_bufs`] for types where large
     /// [`Bytes`] fields go via push; failing to do so will over-allocate.
+    #[inline]
     fn encode_inline_size(&self) -> usize {
         self.encode_size()
     }
+
+    /// Returns the total inline encoded size of a sequence, excluding any container-specific
+    /// length prefix.
+    ///
+    /// This hidden hook is the slice equivalent of [EncodeSize::encode_inline_size]. The
+    /// default preserves normal element-by-element sizing. Fixed-size implementations override
+    /// this to compute `SIZE * len`, matching [EncodeSize::encode_size_slice] for the
+    /// [`Write::write_bufs`] path.
+    ///
+    /// This hook exists because stable Rust cannot express the overlapping specialized
+    /// container impls that would otherwise provide this aggregate path directly.
+    ///
+    /// This is hidden from generated documentation for the same reason as
+    /// [EncodeSize::encode_size_slice].
+    #[doc(hidden)]
+    #[inline]
+    fn encode_inline_size_slice(values: &[Self]) -> usize
+    where
+        Self: Sized,
+    {
+        values
+            .iter()
+            .map(EncodeSize::encode_inline_size)
+            .sum::<usize>()
+    }
 }
 
 // Automatically implement `EncodeSize` for types that are `FixedSize`.
 impl<T: FixedSize> EncodeSize for T {
+    #[inline]
     fn encode_size(&self) -> usize {
         Self::SIZE
     }
+
+    #[inline]
+    fn encode_size_slice(values: &[Self]) -> usize
+    where
+        Self: Sized,
+    {
+        Self::SIZE * values.len()
+    }
+
+    #[inline]
+    fn encode_inline_size_slice(values: &[Self]) -> usize
+    where
+        Self: Sized,
+    {
+        Self::encode_size_slice(values)
+    }
 }
 
 /// Trait for types that can be written (encoded) to a byte buffer.
@@ -46,12 +116,57 @@ pub trait Write {
     /// Implementations should panic if the buffer doesn't have enough capacity.
     fn write(&self, buf: &mut impl BufMut);
 
+    /// Writes the encoded payload for a sequence, excluding any container-specific length
+    /// prefix.
+    ///
+    /// Container implementations call this hook so element types can provide a more efficient
+    /// aggregate write path. The default preserves normal element-by-element encoding.
+    ///
+    /// This hook exists because stable Rust cannot express the overlapping specialized
+    /// container impls that would otherwise provide this aggregate path directly.
+    ///
+    /// This is hidden from generated documentation because it is an implementation hook for
+    /// codec's container types, not part of the intended user-facing API. Most users should
+    /// implement [Write::write] instead.
+    #[doc(hidden)]
+    #[inline]
+    fn write_slice(values: &[Self], buf: &mut impl BufMut)
+    where
+        Self: Sized,
+    {
+        for item in values {
+            item.write(buf);
+        }
+    }
+
     /// Writes to a [`BufsMut`], allowing existing [`Bytes`] chunks to be
     /// appended via [`BufsMut::push`] instead of written inline. Must encode
     /// to the same format as [`Write::write`]. Defaults to [`Write::write`].
+    #[inline]
     fn write_bufs(&self, buf: &mut impl BufsMut) {
         self.write(buf);
     }
+
+    /// Writes the encoded payload for a sequence to a [`BufsMut`], excluding any
+    /// container-specific length prefix.
+    ///
+    /// This hidden hook is the slice equivalent of [Write::write_bufs]. The default preserves
+    /// normal element-by-element encoding.
+    ///
+    /// This hook exists because stable Rust cannot express the overlapping specialized
+    /// container impls that would otherwise provide this aggregate path directly.
+    ///
+    /// This is hidden from generated documentation for the same reason as [Write::write_slice].
+    #[doc(hidden)]
+    #[inline]
+    fn write_slice_bufs(values: &[Self], buf: &mut impl BufsMut)
+    where
+        Self: Sized,
+    {
+        for item in values {
+            item.write_bufs(buf);
+        }
+    }
 }
 
 /// Trait for types that can be read (decoded) from a byte buffer.
@@ -71,6 +186,44 @@ pub trait Read: Sized {
     /// Returns [Error] if decoding fails due to invalid data, insufficient bytes in the buffer,
     /// or violation of constraints imposed by the `cfg`.
     fn read_cfg(buf: &mut impl Buf, cfg: &Self::Cfg) -> Result<Self, Error>;
+
+    /// Reads `len` values from the buffer into a vector.
+    ///
+    /// Container implementations call this hook so element types can provide a more efficient
+    /// vector read path. The default preserves normal element-by-element decoding.
+    ///
+    /// This hook exists because stable Rust cannot express the overlapping specialized
+    /// container impls that would otherwise provide this aggregate path directly.
+    ///
+    /// This is hidden from generated documentation because it is an implementation hook for
+    /// codec's container types, not part of the intended user-facing API. Most users should
+    /// implement [Read::read_cfg] instead.
+    #[doc(hidden)]
+    #[inline]
+    fn read_vec(buf: &mut impl Buf, len: usize, cfg: &Self::Cfg) -> Result<Vec<Self>, Error> {
+        let mut values = Vec::with_capacity(len);
+        for _ in 0..len {
+            values.push(Self::read_cfg(buf, cfg)?);
+        }
+        Ok(values)
+    }
+
+    /// Reads exactly `N` values from the buffer into an array.
+    ///
+    /// This hidden hook is the array equivalent of [Read::read_vec]. The default preserves
+    /// normal element-by-element decoding.
+    ///
+    /// This hook exists because stable Rust cannot express the overlapping specialized array
+    /// impls that would otherwise provide this aggregate path directly.
+    ///
+    /// This is hidden from generated documentation for the same reason as [Read::read_vec].
+    #[doc(hidden)]
+    #[inline]
+    fn read_array<const N: usize>(buf: &mut impl Buf, cfg: &Self::Cfg) -> Result<[Self; N], Error> {
+        Ok(Self::read_vec(buf, N, cfg)?
+            .try_into()
+            .unwrap_or_else(|_| unreachable!("array length should match capacity")))
+    }
 }
 
 /// Trait combining [Write] and [EncodeSize] for types that can be fully encoded.

codec/src/codec.rs

@@ -32,14 +32,32 @@
 //!   that the entire buffer is consumed.
 //! - [Codec]: Combines [Encode] + [Decode].
 //!
+//! # Specialization
+//!
+//! Byte-oriented container paths use hidden trait hooks on [Write], [Read], and [EncodeSize] to
+//! select bulk-copy implementations while keeping generic fallbacks. Container implementations
+//! call hooks such as `T::write_slice`, `T::read_vec`, and `T::encode_size_slice`. The default
+//! methods preserve element-by-element behavior, while concrete element implementations can
+//! override only the paths they can make faster.
+//!
+//! Encoding specialization has two parts: aggregate sizing and aggregate writing. For example,
+//! `Vec<u8>::encode()` first asks for the output size, then writes the bytes. The [EncodeSize]
+//! slice hooks let fixed-size elements compute `SIZE * len` without scanning every element, while
+//! the [Write] slice hooks let byte containers write the payload with one bulk copy.
+//!
+//! These hooks keep the container code generic: a container like `Vec<T>` calls one element-level
+//! method for sizing, writing, or reading, and the element implementation decides whether the
+//! default element-by-element behavior or a bulk path applies.
+//!
 //! # Supported Types
 //!
 //! Natively supports encoding/decoding for:
 //! - Primitives: [bool],
 //!   [u8], [u16], [u32], [u64], [u128],
 //!   [i8], [i16], [i32], [i64], [i128],
-//!   [f32], [f64], [u8; N],
-//!   and [usize] (must fit within a [u32] for cross-platform compatibility).
+//!   [f32], [f64], and [usize] (must fit within a [u32] for cross-platform compatibility).
+//! - Arrays: `[T; N]` supports [Write] and [Read] when `T` does, and supports [FixedSize],
+//!   [Encode], [Codec], [EncodeFixed], and [CodecFixed] when `T: FixedSize`.
 //! - Collections: [`Vec`], [`Option`], `BTreeMap`, `BTreeSet`
 //! - Tuples: `(T1, T2, ...)` (up to 12 elements)
 //! - Common External Types: [::bytes::Bytes]

codec/src/lib.rs

@@ -105,3 +105,145 @@ where
 
     Ok(())
 }
+
+#[cfg(test)]
+pub(crate) mod tests {
+    use crate::{BufsMut, Error, Read, Write};
+    use bytes::{buf::UninitSlice, Buf, BufMut, Bytes, BytesMut};
+
+    /// One-byte test type that uses the default aggregate hooks.
+    ///
+    /// This lets tests distinguish the generic per-element path from the
+    /// specialized `u8` path while keeping the same encoded representation.
+    #[derive(Debug, PartialEq, Eq)]
+    pub struct Byte(pub u8);
+
+    impl Write for Byte {
+        fn write(&self, buf: &mut impl BufMut) {
+            buf.put_u8(self.0);
+        }
+    }
+
+    impl Read for Byte {
+        type Cfg = ();
+
+        fn read_cfg(buf: &mut impl Buf, _: &()) -> Result<Self, Error> {
+            Ok(Self(<u8 as Read>::read_cfg(buf, &())?))
+        }
+    }
+
+    /// Test [`BufMut`] implementation that records how values are written.
+    ///
+    /// Specialization-selection tests use this to assert whether a container
+    /// wrote its payload with one aggregate [`BufMut::put_slice`] call or with
+    /// per-element [`BufMut::put_u8`] calls.
+    pub struct TrackingWriteBuf {
+        inner: BytesMut,
+        /// Number of aggregate slice writes.
+        pub put_slice_calls: usize,
+        /// Number of single-byte writes.
+        pub put_u8_calls: usize,
+        /// Number of externally pushed chunks.
+        pub push_calls: usize,
+    }
+
+    impl TrackingWriteBuf {
+        pub fn new() -> Self {
+            Self {
+                inner: BytesMut::new(),
+                put_slice_calls: 0,
+                put_u8_calls: 0,
+                push_calls: 0,
+            }
+        }
+
+        pub fn freeze(self) -> Bytes {
+            self.inner.freeze()
+        }
+    }
+
+    // SAFETY: `TrackingWriteBuf` delegates storage and cursor management to
+    // `BytesMut`, which upholds the `BufMut` invariants. The overridden write
+    // methods only count calls before forwarding.
+    unsafe impl BufMut for TrackingWriteBuf {
+        fn remaining_mut(&self) -> usize {
+            self.inner.remaining_mut()
+        }
+
+        fn chunk_mut(&mut self) -> &mut UninitSlice {
+            self.inner.chunk_mut()
+        }
+
+        unsafe fn advance_mut(&mut self, cnt: usize) {
+            // SAFETY: The caller guarantees that `cnt` bytes in the current
+            // chunk were initialized. `BytesMut` owns the cursor state and
+            // enforces the remaining invariants.
+            unsafe { self.inner.advance_mut(cnt) }
+        }
+
+        fn put_slice(&mut self, src: &[u8]) {
+            self.put_slice_calls += 1;
+            self.inner.put_slice(src);
+        }
+
+        fn put_u8(&mut self, n: u8) {
+            self.put_u8_calls += 1;
+            self.inner.put_u8(n);
+        }
+    }
+
+    impl BufsMut for TrackingWriteBuf {
+        fn push(&mut self, bytes: impl Into<Bytes>) {
+            let bytes = bytes.into();
+            self.push_calls += 1;
+            self.inner.extend_from_slice(&bytes);
+        }
+    }
+
+    /// Test [`Buf`] implementation that records how values are read.
+    ///
+    /// Specialization-selection tests use this to assert whether a container
+    /// read its payload with one aggregate [`Buf::copy_to_slice`] call or with
+    /// per-element [`Buf::get_u8`] calls.
+    pub struct TrackingReadBuf {
+        inner: Bytes,
+        /// Number of aggregate slice reads.
+        pub copy_to_slice_calls: usize,
+        /// Number of single-byte reads.
+        pub get_u8_calls: usize,
+    }
+
+    impl TrackingReadBuf {
+        pub fn new(bytes: &'static [u8]) -> Self {
+            Self {
+                inner: Bytes::from_static(bytes),
+                copy_to_slice_calls: 0,
+                get_u8_calls: 0,
+            }
+        }
+    }
+
+    impl Buf for TrackingReadBuf {
+        fn remaining(&self) -> usize {
+            self.inner.remaining()
+        }
+
+        fn chunk(&self) -> &[u8] {
+            self.inner.chunk()
+        }
+
+        fn advance(&mut self, cnt: usize) {
+            self.inner.advance(cnt)
+        }
+
+        fn copy_to_slice(&mut self, dst: &mut [u8]) {
+            self.copy_to_slice_calls += 1;
+            self.inner.copy_to_slice(dst);
+        }
+
+        fn get_u8(&mut self) -> u8 {
+            self.get_u8_calls += 1;
+            self.inner.get_u8()
+        }
+    }
+}