devela::all

Trait MemPod

Source 
pub unsafe trait MemPod: Copy + 'static {
    // Provided methods
    fn zeroed() -> Self { ... }
    fn from_bytes(bytes: &[u8]) -> Self { ... }
    fn as_bytes(&self) -> &[u8] ⓘ { ... }
    fn as_bytes_mut(&mut self) -> &mut [u8] ⓘ { ... }
}
Available on crate feature unsafe_layout only.
Expand description

Indicates a type is Plain Old Data, and meets specific memory layout guarantees.

Types that implement this trait are guaranteed to be safe for certain low-level memory operations, such as transmuting to and from byte slices, copying, and interfacing with C code.

§Safety

Implementing MemPod is unsafe because it requires the implementer to ensure the following invariants:

  1. No Padding: The type must not contain any padding bytes. This ensures that the memory representation of the type is fully defined by its fields.

  2. Safe to Transmute: The type must be safe to transmute to and from a byte slice (&[u8]). This requires that the type’s memory layout is consistent and well-defined across different platforms.

  3. Copyable: The type must implement Copy, meaning it can be duplicated simply by copying its bits. This is a fundamental property of POD types.

  4. Valid Bit Patterns: Any bit pattern must represent a valid instance of the type. This means that transmuting arbitrary bytes into the type must always produce a valid value, and no bit pattern can cause undefined behavior when interpreted as this type.

§Implementing MemPod

When implementing MemPod, it is recommended to use #[repr(C)] or #[repr(transparent)] on the type to ensure a well-defined and predictable memory layout. This is particularly important when dealing with FFI or any situation where the exact memory layout of the type is critical.

Note that only types that are Copy can implement MemPod. This is because POD types inherently need to be trivially copyable without any additional logic (e.g. no destructors).

§Use Cases

  • FFI Compatibility: MemPod types can be safely passed between Rust and C, as they have a predictable memory layout.
  • Efficient Serialization: MemPod types can be directly serialized to or deserialized from a byte buffer, making them ideal for low-level data manipulation and storage.
  • Memory Safety: By ensuring that types implementing MemPod adhere to strict memory guarantees, you can safely perform low-level operations without risking undefined behavior.

§Examples

use devela::sys::mem::MemPod;

// Define a simple structure that can be safely used as POD.
#[derive(Copy, Clone)]
#[repr(C)]  // Ensure a predictable memory layout compatible with C.
struct MyStruct {
    pub a: u8,
    pub b: i16,
    pub c: u32,
}

unsafe impl MemPod for MyStruct {}

Provided Methods§

Source

fn zeroed() -> Self

Returns a new instance contrcuted from zeroes.

Source

fn from_bytes(bytes: &[u8]) -> Self

Returns a new instance constructed from the given bytes.

If the byte slice is too small, the remaining bytes will be 0.

Source

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

Returns the instance’s data as a slice of bytes.

Source

fn as_bytes_mut(&mut self) -> &mut [u8] ⓘ

Returns the instance’s data as a mutable slice of bytes.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types§

Source§

impl MemPod for f32

Source§

impl MemPod for f64

Source§

impl MemPod for i8

Source§

impl MemPod for i16

Source§

impl MemPod for i32

Source§

impl MemPod for i64

Source§

impl MemPod for i128

Source§

impl MemPod for isize

Source§

impl MemPod for u8

Source§

impl MemPod for u16

Source§

impl MemPod for u32

Source§

impl MemPod for u64

Source§

impl MemPod for u128

Source§

impl MemPod for ()

Source§

impl MemPod for usize

Source§

impl<T: MemPod, const N: usize> MemPod for [T; N]

Implementors§