Interface ParcodeItem

src/reader.rs:337–437

A trait for types that can be read from a shard (payload + children). This trait is used internally during parallel reconstruction to deserialize individual items or slices of items from shard payloads. It provides two methods: - [`read_from_shard`](Self::read_from_shard): Reads a single item - [`read_slice_from_shard`](Self::read_slice_from_shard): Reads multiple items (optimized) ## Automatic

/// Implementations must be `Send + Sync + 'static` to support parallel reconstruction across
/// threads. This is automatically satisfied for most types.
pub trait ParcodeItem: Sized + Send + Sync + 'static {
    /// Reads a single item from the shard payload and children.
    ///
    /// This method is called during deserialization to reconstruct individual items from
    /// a shard's payload. For types with chunkable fields, this method should deserialize
    /// local fields from the reader and reconstruct remote fields from the children iterator.
    ///
    /// ## Parameters
    ///
    /// * `reader`: Cursor over the shard's decompressed payload
    /// * `children`: Iterator over child nodes (for chunkable fields)
    ///
    /// ## Returns
    ///
    /// The deserialized item.
    ///
    /// ## Errors
    ///
    /// Returns an error if deserialization fails or children are missing.
    fn read_from_shard(
        reader: &mut std::io::Cursor<&[u8]>,
        children: &mut std::vec::IntoIter<ChunkNode<'_>>,
    ) -> Result<Self>;

    /// DEPRECATED in favor of `read_into_slice` internally, but kept for API compat.
    /// Default impl now delegates to `read_into_slice` to reduce code duplication.
    fn read_slice_from_shard(
        reader: &mut std::io::Cursor<&[u8]>,
        children: &mut std::vec::IntoIter<ChunkNode<'_>>,
    ) -> Result<Vec<Self>> {
        let start_pos = reader.position();

        // Read length prefix
        let len: u64 = bincode::serde::decode_from_std_read(reader, bincode::config::standard())
            .map_err(|e| ParcodeError::Serialization(e.to_string()))?;

        let count = usize::try_from(len)
            .map_err(|_| ParcodeError::Serialization("Vector length exceeds usize".into()))?;

        // Allocate uninit vec
        let mut uninit_vec: Vec<MaybeUninit<Self>> = Vec::with_capacity(count);
        #[allow(unsafe_code)]
        unsafe {
            uninit_vec.set_len(count);
        }

        reader.set_position(start_pos);

        let read_count = Self::read_into_slice(reader, children, &mut uninit_vec)?;

        if read_count != count {
            return Err(ParcodeError::Format("Mismatch in read count".into()));
        }

        // Transmute to Vec<T>
        #[allow(unsafe_code)]
        let final_vec = unsafe {
            let mut manual = ManuallyDrop::new(uninit_vec);