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.
Required Associated Constants§
Sourceconst BASE_SIZE: usize
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§
Provided Methods§
Sourcefn dst_len(header: &Self::Header) -> Self::Metadata
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.
For sized tags, this just returns (). For DSTs, this returns an
usize.
Sourcefn payload(&self) -> &[u8] ⓘ
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.
Sourcefn as_bytes(&self) -> &[u8] ⓘ
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.
Sourcefn as_ptr(&self) -> *const Self::Header
fn as_ptr(&self) -> *const Self::Header
Returns a pointer to this structure.
Examples found in repository?
7fn main() {
8 // We create a Multiboot2 header during runtime here. A more practical
9 // example, however, would be that you parse the header from kernel binary
10 // at runtime.
11 let header_bytes = Builder::new(HeaderTagISA::I386)
12 .relocatable_tag(RelocatableHeaderTag::new(
13 HeaderTagFlag::Required,
14 0x1337,
15 0xdeadbeef,
16 4096,
17 RelocatableHeaderTagPreference::None,
18 ))
19 .information_request_tag(InformationRequestHeaderTag::new(
20 HeaderTagFlag::Required,
21 &[MbiTagType::Cmdline, MbiTagType::BootLoaderName],
22 ))
23 .build();
24
25 let header = unsafe { Header::load(header_bytes.as_ptr()) }.unwrap();
26 println!("{header:#?}");
27}Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".