Trait zerocopy::FromZeroes

source ·

pub unsafe trait FromZeroes {
    // Provided methods
    fn zero(&mut self) { ... }
    fn new_zeroed() -> Self
       where Self: Sized { ... }
    fn new_box_zeroed() -> Box<Self>
       where Self: Sized { ... }
    fn new_box_slice_zeroed(len: usize) -> Box<[Self]>
       where Self: Sized { ... }
    fn new_vec_zeroed(len: usize) -> Vec<Self>
       where Self: Sized { ... }
}

Expand description

Types for which a sequence of bytes all set to zero represents a valid instance of the type.

Any memory region of the appropriate length which is guaranteed to contain only zero bytes can be viewed as any FromZeroes type with no runtime overhead. This is useful whenever memory is known to be in a zeroed state, such memory returned from some allocation routines.

Implementation

Do not implement this trait yourself! Instead, use #[derive(FromZeroes)] (requires the derive Cargo feature); e.g.:

#[derive(FromZeroes)]
struct MyStruct {
    ...
}

#[derive(FromZeroes)]
#[repr(u8)]
enum MyEnum {
    ...
}

#[derive(FromZeroes)]
union MyUnion {
    ...
}

This derive performs a sophisticated, compile-time safety analysis to determine whether a type is FromZeroes.

Safety

This section describes what is required in order for T: FromZeroes, and what unsafe code may assume of such types. If you don’t plan on implementing FromZeroes manually, and you don’t plan on writing unsafe code that operates on FromZeroes types, then you don’t need to read this section.

If T: FromZeroes, then unsafe code may assume that:

It is sound to treat any initialized sequence of zero bytes of length size_of::<T>() as a T.
Given b: &[u8] where b.len() == size_of::<T>(), b is aligned to align_of::<T>(), and b contains only zero bytes, it is sound to construct a t: &T at the same address as b, and it is sound for both b and t to be live at the same time.

If a type is marked as FromZeroes which violates this contract, it may cause undefined behavior.

#[derive(FromZeroes)] only permits types which satisfy these requirements.

Provided Methods§

source

fn zero(&mut self)

Overwrites self with zeroes.

Sets every byte in self to 0. While this is similar to doing *self = Self::new_zeroed(), it differs in that zero does not semantically drop the current value and replace it with a new one - it simply modifies the bytes of the existing value.

Examples

#[derive(FromZeroes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

let mut header = PacketHeader {
    src_port: 100u16.to_be_bytes(),
    dst_port: 200u16.to_be_bytes(),
    length: 300u16.to_be_bytes(),
    checksum: 400u16.to_be_bytes(),
};

header.zero();

assert_eq!(header.src_port, [0, 0]);
assert_eq!(header.dst_port, [0, 0]);
assert_eq!(header.length, [0, 0]);
assert_eq!(header.checksum, [0, 0]);

source

fn new_zeroed() -> Self
where Self: Sized,

Creates an instance of Self from zeroed bytes.

Examples

#[derive(FromZeroes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

let header: PacketHeader = FromZeroes::new_zeroed();

assert_eq!(header.src_port, [0, 0]);
assert_eq!(header.dst_port, [0, 0]);
assert_eq!(header.length, [0, 0]);
assert_eq!(header.checksum, [0, 0]);

source

fn new_box_zeroed() -> Box<Self>
where Self: Sized,

Available on crate feature alloc only.

Creates a Box<Self> from zeroed bytes.

This function is useful for allocating large values on the heap and zero-initializing them, without ever creating a temporary instance of Self on the stack. For example, <[u8; 1048576]>::new_box_zeroed() will allocate [u8; 1048576] directly on the heap; it does not require storing [u8; 1048576] in a temporary variable on the stack.

On systems that use a heap implementation that supports allocating from pre-zeroed memory, using new_box_zeroed (or related functions) may have performance benefits.

Note that Box<Self> can be converted to Arc<Self> and other container types without reallocation.

Panics

Panics if allocation of size_of::<Self>() bytes fails.

source

fn new_box_slice_zeroed(len: usize) -> Box<[Self]>
where Self: Sized,

Available on crate feature alloc only.

Creates a Box<[Self]> (a boxed slice) from zeroed bytes.

This function is useful for allocating large values of [Self] on the heap and zero-initializing them, without ever creating a temporary instance of [Self; _] on the stack. For example, u8::new_box_slice_zeroed(1048576) will allocate the slice directly on the heap; it does not require storing the slice on the stack.

On systems that use a heap implementation that supports allocating from pre-zeroed memory, using new_box_slice_zeroed may have performance benefits.

If Self is a zero-sized type, then this function will return a Box<[Self]> that has the correct len. Such a box cannot contain any actual information, but its len() property will report the correct value.

Panics

Panics if size_of::<Self>() * len overflows.
Panics if allocation of size_of::<Self>() * len bytes fails.

source

fn new_vec_zeroed(len: usize) -> Vec<Self>
where Self: Sized,

Available on crate feature new_vec_zeroed only.

Creates a Vec<Self> from zeroed bytes.

This function is useful for allocating large values of Vecs and zero-initializing them, without ever creating a temporary instance of [Self; _] (or many temporary instances of Self) on the stack. For example, u8::new_vec_zeroed(1048576) will allocate directly on the heap; it does not require storing intermediate values on the stack.

On systems that use a heap implementation that supports allocating from pre-zeroed memory, using new_vec_zeroed may have performance benefits.

If Self is a zero-sized type, then this function will return a Vec<Self> that has the correct len. Such a Vec cannot contain any actual information, but its len() property will report the correct value.

Panics

Panics if size_of::<Self>() * len overflows.
Panics if allocation of size_of::<Self>() * len bytes fails.

Trait zerocopy::FromZeroes

Provided Methods§

fn zero(&mut self)

fn new_zeroed() -> Selfwhere Self: Sized,

fn new_box_zeroed() -> Box<Self>where Self: Sized,

fn new_box_slice_zeroed(len: usize) -> Box<[Self]>where Self: Sized,

fn new_vec_zeroed(len: usize) -> Vec<Self>where Self: Sized,

Implementations on Foreign Types§

impl FromZeroes for Option<NonZeroI8>

impl FromZeroes for Option<NonZeroI16>

impl FromZeroes for Option<NonZeroI32>

impl FromZeroes for Option<NonZeroI64>

impl FromZeroes for Option<NonZeroI128>

impl FromZeroes for Option<NonZeroIsize>

impl FromZeroes for Option<NonZeroU8>

impl FromZeroes for Option<NonZeroU16>

impl FromZeroes for Option<NonZeroU32>

impl FromZeroes for Option<NonZeroU64>

impl FromZeroes for Option<NonZeroU128>

impl FromZeroes for Option<NonZeroUsize>

impl FromZeroes for bool

impl FromZeroes for char

impl FromZeroes for f32

impl FromZeroes for f64

impl FromZeroes for i8

impl FromZeroes for i16

impl FromZeroes for i32

impl FromZeroes for i64

impl FromZeroes for i128

impl FromZeroes for isize

impl FromZeroes for str

impl FromZeroes for u8

impl FromZeroes for u16

impl FromZeroes for u32

impl FromZeroes for u64

impl FromZeroes for u128

impl FromZeroes for ()

impl FromZeroes for usize

impl FromZeroes for __m128

impl FromZeroes for __m128d

impl FromZeroes for __m128i

impl FromZeroes for __m256

impl FromZeroes for __m256d

impl FromZeroes for __m256i

impl FromZeroes for __m512

impl FromZeroes for __m512bh

impl FromZeroes for __m512d

impl FromZeroes for __m512i

impl<A, B, C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: A, _: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<A, B, C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: A, _: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<B, C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<B, C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<E, F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<E, F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<G, H, I, J, K, L, M> FromZeroes for Option<fn(_: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<H, I, J, K, L, M> FromZeroes for Option<fn(_: H, _: I, _: J, _: K, _: L) -> M>

impl<H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: H, _: I, _: J, _: K, _: L) -> M>

impl<I, J, K, L, M> FromZeroes for Option<fn(_: I, _: J, _: K, _: L) -> M>

impl<I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: I, _: J, _: K, _: L) -> M>

impl<J, K, L, M> FromZeroes for Option<fn(_: J, _: K, _: L) -> M>

impl<J, K, L, M> FromZeroes for Option<extern "C" fn(_: J, _: K, _: L) -> M>

impl<K, L, M> FromZeroes for Option<fn(_: K, _: L) -> M>

impl<K, L, M> FromZeroes for Option<extern "C" fn(_: K, _: L) -> M>

impl<L, M> FromZeroes for Option<fn(_: L) -> M>

impl<L, M> FromZeroes for Option<extern "C" fn(_: L) -> M>

impl<M> FromZeroes for Option<fn() -> M>

impl<M> FromZeroes for Option<extern "C" fn() -> M>

impl<T> FromZeroes for Option<&T>

impl<T> FromZeroes for Option<&mut T>

impl<T> FromZeroes for Option<Box<T>>

impl<T> FromZeroes for Option<NonNull<T>>

impl<T> FromZeroes for *const T

impl<T> FromZeroes for *mut T

fn new_zeroed() -> Self
where Self: Sized,

fn new_box_zeroed() -> Box<Self>
where Self: Sized,

fn new_box_slice_zeroed(len: usize) -> Box<[Self]>
where Self: Sized,

fn new_vec_zeroed(len: usize) -> Vec<Self>
where Self: Sized,

impl<O> FromZeroes for F32<O>
where [u8; 4]: FromZeroes, PhantomData<O>: FromZeroes,

impl<O> FromZeroes for F64<O>
where [u8; 8]: FromZeroes, PhantomData<O>: FromZeroes,

impl<O> FromZeroes for I16<O>
where [u8; 2]: FromZeroes, PhantomData<O>: FromZeroes,

impl<O> FromZeroes for I32<O>
where [u8; 4]: FromZeroes, PhantomData<O>: FromZeroes,

impl<O> FromZeroes for I64<O>
where [u8; 8]: FromZeroes, PhantomData<O>: FromZeroes,

impl<O> FromZeroes for I128<O>
where [u8; 16]: FromZeroes, PhantomData<O>: FromZeroes,

impl<O> FromZeroes for U16<O>
where [u8; 2]: FromZeroes, PhantomData<O>: FromZeroes,

impl<O> FromZeroes for U32<O>
where [u8; 4]: FromZeroes, PhantomData<O>: FromZeroes,

impl<O> FromZeroes for U64<O>
where [u8; 8]: FromZeroes, PhantomData<O>: FromZeroes,

impl<O> FromZeroes for U128<O>
where [u8; 16]: FromZeroes, PhantomData<O>: FromZeroes,

impl<T> FromZeroes for Unalign<T>
where T: FromZeroes,