Trait MaybeDynSized

Source

pub unsafe trait MaybeDynSized: Pointee {
    type Header: Header;

    const BASE_SIZE: usize;

    // Provided methods
    fn dst_len(header: &Self::Header) -> Self::Metadata
       where Self::Metadata: Default { ... }
    fn header(&self) -> &Self::Header { ... }
    fn payload(&self) -> &[u8] ⓘ { ... }
    fn as_bytes(&self) -> &[u8] ⓘ { ... }
    fn as_ptr(&self) -> *const Self::Header { ... }
}

Expand description

A trait to abstract sized and unsized structures (DSTs). It enables casting a DynSizedStructure to sized or unsized structures using DynSizedStructure::cast.

Structs that are a DST must provide a correct MaybeDynSized::dst_len implementation. The needed metadata type is either () for sized types or usize for dynamically sized types. For sized types, there is a default implementation. Only dynamically sized types need to implement MaybeDynSized::dst_len.

§Safety

Implementors must be #[repr(C)], start with Self::Header, have an alignment of at most ALIGNMENT, and allow every bit pattern.

MaybeDynSized::BASE_SIZE, MaybeDynSized::dst_len, and Header::total_size must correctly describe the initialized, contiguous memory backing the value. Incorrect sizes or implicit padding within the reported range can cause out-of-bounds references. Trailing padding beyond that range is fine.

Note that for sized implementors, the requirements above imply that size_of::<Self>() exceeds MaybeDynSized::BASE_SIZE at most by trailing padding up to the type’s alignment. Same-size casts rely on this to keep the created reference within the source allocation.

Required Associated Constants§

Source

const BASE_SIZE: usize

The true base size of the struct without any implicit or additional padding. Note that size_of::<T>() isn’t sufficient, as for example the type could have three u32 fields, which would add an implicit u32 padding. However, this constant must always fulfill BASE_SIZE >= size_of::<Self::Header>().

The main purpose of this constant is to create awareness when you implement Self::dst_len, where you should use this. If this value is correct, we prevent situations where we read uninitialized bytes, especially when creating tags in builders.

Required Associated Types§

The associated Header of this tag.

Provided Methods§

Source

fn dst_len(header: &Self::Header) -> Self::Metadata
where Self::Metadata: Default,

Returns the amount of items in the dynamically sized portion of the DST. Note that this is not the amount of bytes. So if the dynamically sized portion is 16 bytes in size and each element is 4 bytes big, then this function must return 4.

For sized tags, this just returns (). For DSTs, this returns an usize.

Returns the corresponding Header.

Source

fn payload(&self) -> &[u8] ⓘ

Returns the payload, i.e., all memory that is not occupied by the Header of the type. Implicit trailing padding beyond the structure size reported in the header is not part of the payload.

§Panics

Panics if the size reported in the header is smaller than the size of the Header itself, which can only happen for oddly formed values.

Source

fn as_bytes(&self) -> &[u8] ⓘ

Returns the bytes of the structure, i.e., the header and the payload, up to the structure size reported by Self::header.

Implicit trailing padding that the Rust memory layout might add beyond that size is excluded, as it may be uninitialized for stack-constructed values and must never be read.

Source