Trait AncillaryData

pub trait AncillaryData: Sized {
    const SIZE: usize = _;

    // Required methods
    fn encode(&self, buffer: &mut [MaybeUninit<u8>]) -> Result<(), CodecError>;
    fn decode(buffer: &[u8]) -> Result<Self, CodecError>;
}

Available on crate features io and ancillary only.

Expand description

Trait for types that can be encoded and decoded as ancillary data payloads.

This trait enables a type to be used as the data payload in control messages (ancillary data). Types implementing this trait can be passed to AncillaryBuilder::push and retrieved via AncillaryRef::data.

§Built-in Implementations

This trait is implemented for the following platform-specific types:

Unix: libc::in_addr, libc::in_pktinfo, libc::in6_pktinfo
Windows: IN_PKTINFO, IN6_PKTINFO

When the bytemuck feature is enabled, this trait is also automatically implemented for types that implement bytemuck_ext::BitwiseAncillaryData:

Primitive types: (), u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize, f32, f64
Fixed-size arrays of the above types (up to size 512)

For custom types with the bytemuck feature enabled, you can implement bytemuck_ext::BitwiseAncillaryData to automatically get AncillaryData (see bytemuck_ext for details). Otherwise, you must manually implement this trait with custom encoding/decoding logic.

§Example

use std::mem::MaybeUninit;

use compio_io::ancillary::{AncillaryData, CodecError};

struct MyData {
    value: u32,
}

impl AncillaryData for MyData {
    const SIZE: usize = std::mem::size_of::<u32>();

    fn encode(&self, buffer: &mut [MaybeUninit<u8>]) -> Result<(), CodecError> {
        if buffer.len() < Self::SIZE {
            return Err(CodecError::BufferTooSmall);
        }
        let bytes = self.value.to_ne_bytes();
        for (i, &byte) in bytes.iter().enumerate() {
            buffer[i] = MaybeUninit::new(byte);
        }
        Ok(())
    }

    fn decode(buffer: &[u8]) -> Result<Self, CodecError> {
        if buffer.len() < Self::SIZE {
            return Err(CodecError::BufferTooSmall);
        }
        let mut bytes = [0u8; 4];
        bytes.copy_from_slice(&buffer[..4]);
        Ok(MyData {
            value: u32::from_ne_bytes(bytes),
        })
    }
}