Struct DstLayout

Source

#[doc(hidden)] pub struct DstLayout { /* private fields */ }

Expand description

The layout of a type which might be dynamically-sized.

DstLayout describes the layout of sized types, slice types, and “slice DSTs” - ie, those that are known by the type system to have a trailing slice (as distinguished from dyn Trait types - such types might have a trailing slice type, but the type system isn’t aware of it).

Note that DstLayout does not have any internal invariants, so no guarantee is made that a DstLayout conforms to any of Rust’s requirements regarding the layout of real Rust types or instances of types.

Implementations§

Source §

impl DstLayout

Source

#[doc(hidden)] pub const fn new_zst( repr_align: Option<NonZeroUsize>, ) -> DstLayout

Constructs a DstLayout for a zero-sized type with repr_align alignment (or 1). If repr_align is provided, then it must be a power of two.

§Panics

This function panics if the supplied repr_align is not a power of two.

§Safety

Unsafe code may assume that the contract of this function is satisfied.

Source

#[doc(hidden)] pub const fn for_type<T>() -> DstLayout

Constructs a DstLayout which describes T and assumes T may contain padding.

§Safety

Unsafe code may assume that DstLayout is the correct layout for T.

Source

#[doc(hidden)] pub const fn for_unpadded_type<T>() -> DstLayout

Constructs a DstLayout which describes a T that does not contain padding.

§Safety

Unsafe code may assume that DstLayout is the correct layout for T.

Source

pub const fn for_repr_c_struct( repr_align: Option<NonZeroUsize>, repr_packed: Option<NonZeroUsize>, fields: &[DstLayout], ) -> DstLayout

Constructs a complete DstLayout reflecting a repr(C) struct with the given alignment modifiers and fields.

This method cannot be used to match the layout of a record with the default representation, as that representation is mostly unspecified.

§Safety

For any definition of a repr(C) struct, if this method is invoked with alignment modifiers and fields corresponding to that definition, the resulting DstLayout will correctly encode the layout of that struct.

We make no guarantees to the behavior of this method when it is invoked with arguments that cannot correspond to a valid repr(C) struct.

Source

#[doc(hidden)] pub const fn extend( self, field: DstLayout, repr_packed: Option<NonZeroUsize>, ) -> Self

Like Layout::extend, this creates a layout that describes a record whose layout consists of self followed by next that includes the necessary inter-field padding, but not any trailing padding.

In order to match the layout of a #[repr(C)] struct, this method should be invoked for each field in declaration order. To add trailing padding, call DstLayout::pad_to_align after extending the layout for all fields. If self corresponds to a type marked with repr(packed(N)), then repr_packed should be set to Some(N), otherwise None.

This method cannot be used to match the layout of a record with the default representation, as that representation is mostly unspecified.

§Safety

If a (potentially hypothetical) valid repr(C) Rust type begins with fields whose layout are self, and those fields are immediately followed by a field whose layout is field, then unsafe code may rely on self.extend(field, repr_packed) producing a layout that correctly encompasses those two components.

We make no guarantees to the behavior of this method if these fragments cannot appear in a valid Rust type (e.g., the concatenation of the layouts would lead to a size larger than isize::MAX).

Source

#[doc(hidden)] pub const fn pad_to_align(self) -> Self

Like Layout::pad_to_align, this routine rounds the size of this layout up to the nearest multiple of this type’s alignment or repr_packed (whichever is less). This method leaves DST layouts unchanged, since the trailing padding of DSTs is computed at runtime.

The accompanying boolean is true if the resulting composition of fields necessitated static (as opposed to dynamic) padding; otherwise false.

In order to match the layout of a #[repr(C)] struct, this method should be invoked after the invocations of DstLayout::extend. If self corresponds to a type marked with repr(packed(N)), then repr_packed should be set to Some(N), otherwise None.

This method cannot be used to match the layout of a record with the default representation, as that representation is mostly unspecified.

§Safety

If a (potentially hypothetical) valid repr(C) type begins with fields whose layout are self followed only by zero or more bytes of trailing padding (not included in self), then unsafe code may rely on self.pad_to_align(repr_packed) producing a layout that correctly encapsulates the layout of that type.

We make no guarantees to the behavior of this method if self cannot appear in a valid Rust type (e.g., because the addition of trailing padding would lead to a size larger than isize::MAX).

Source