Skip to main content

AncillaryData

compio::io::ancillary

Trait AncillaryData 

Source 
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 ancillary and io 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),
        })
    }
}

Provided Associated Constants§

Source

const SIZE: usize = _

The size in bytes of the encoded representation.

This defaults to std::mem::size_of::<Self>() but can be overridden for types with custom encoding.

Required Methods§

Source

fn encode(&self, buffer: &mut [MaybeUninit<u8>]) -> Result<(), CodecError>

Encode this value into the provided buffer.

§Errors

Returns CodecError::BufferTooSmall if the buffer is too small to hold the encoded data, or CodecError::Other for other encoding errors.

Source

fn decode(buffer: &[u8]) -> Result<Self, CodecError>

Decode a value from the provided buffer.

§Errors

Returns CodecError::BufferTooSmall if the buffer is too small, or CodecError::Other for other decoding errors.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§