Struct DynSizedStructure

#[repr(C, align(8))]
pub struct DynSizedStructure<H: Header> { /* private fields */ }

An C ABI-compatible dynamically sized type with a common sized Header and a dynamic amount of bytes without hidden implicit padding.

This structures combines a Header with the logically owned data by that header according to the reported Header::payload_len. Instances guarantees that the memory requirements promised in the crates description are respected.

This can be a Multiboot2 header tag, information tag, boot information, or a Multiboot2 header. It is the base for same-size casts to these corresponding structures using DynSizedStructure::cast. Depending on the context, the Header is different (header header, boot information header, header tag header, or boot information tag header).

ABI

This type uses the C ABI. The fixed Header portion is always there. Further, there is a variable amount of payload bytes. Thus, this type can only exist on the heap or references to it can be made by cast via fat pointers. The main constructor is DynSizedStructure::ref_from_bytes.

As terminating padding might be necessary for the proper Rust type layout, size_of_val(&self) might report additional padding bytes that are not reflected by the actual payload. These additional padding bytes however will be reflected in corresponding BytesRef instances from that this structure was created.

Implementations

impl<H: Header> DynSizedStructure<H>

pub fn ref_from_bytes(bytes: BytesRef<'_, H>) -> Result<&Self, MemoryError>

Creates a new fat-pointer backed reference to a DynSizedStructure from the given BytesRef.

pub fn ref_from_slice(bytes: &[u8]) -> Result<&Self, MemoryError>

Creates a new fat-pointer backed reference to a DynSizedStructure from the given &[u8].

pub unsafe fn ref_from_ptr<'a>(ptr: NonNull<H>) -> Result<&'a Self, MemoryError>

Creates a new fat-pointer backed reference to a DynSizedStructure from the given thin pointer to the Header. It reads the total size from the header.

Safety

The caller must ensure that the function operates on valid memory.

pub const fn header(&self) -> &H

Returns the underlying Header.

pub const fn payload(&self) -> &[u8]

Returns the underlying payload.

pub fn cast<T: MaybeDynSized<Header = H> + ?Sized>(&self) -> &T

Performs a memory-safe same-size cast from the base-structure to a specific MaybeDynSized. The idea here is to cast the generic mostly semantic-free version to a specific type with fields that have a clear semantic.

The provided T of type MaybeDynSized might be may be sized type or DST. This depends on the type. However, the source and the target both will have the same actual payload size and the same size_of_val.

Panic

Panics if base assumptions are violated. For example, the T of type MaybeDynSized must allow proper same-size casting to it.

Safety

This function is safe due to various sanity checks and the overall memory assertions done while constructing this type.

Panics

This panics if there is a size mismatch. However, this should never be the case if all types follow their documented requirements.

Trait Implementations

impl<H: Debug + Header> Debug for DynSizedStructure<H>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<H: Header> MaybeDynSized for DynSizedStructure<H>

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>().

type Header = H

The associated Header of this tag.

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

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.

fn header(&self) -> &Self::Header

Returns the corresponding Header.

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

Returns the payload, i.e., all memory that is not occupied by the Header of the type.

fn as_bytes(&self) -> BytesRef<'_, Self::Header>

Returns the whole allocated bytes for this structure encapsulated in BytesRef. This includes padding bytes. To only get the “true” tag data, read the tag size from Self::header and create a sub slice.

fn as_ptr(&self) -> *const Self::Header

Returns a pointer to this structure.

impl<H: PartialEq + Header> PartialEq for DynSizedStructure<H>

fn eq(&self, other: &DynSizedStructure<H>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H: Header> Pointee for DynSizedStructure<H>

where [u8]: Pointee,

type Metadata = <[u8] as Pointee>::Metadata

The metadata type for pointers and references to this type.

impl<H: Eq + Header> Eq for DynSizedStructure<H>

impl<H: Header> StructuralPartialEq for DynSizedStructure<H>