Trait FromZeros

Source

pub unsafe trait FromZeros: TryFromBytes {
    // Provided methods
    fn zero(&mut self) { ... }
    fn new_zeroed() -> Self
       where Self: Sized { ... }
}

Expand description

Types for which a sequence of 0 bytes is a valid instance.

Any memory region of the appropriate length which is guaranteed to contain only zero bytes can be viewed as any FromZeros 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.

§Warning: Padding bytes

Note that, when a value is moved or copied, only the non-padding bytes of that value are guaranteed to be preserved. It is unsound to assume that values written to padding bytes are preserved after a move or copy. For more details, see the FromBytes docs.

§Implementation

Do not implement this trait yourself! Instead, use #[derive(FromZeros)]; e.g.:

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

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

#[derive(FromZeros, Immutable)]
union MyUnion {
    ...
}

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

§Safety

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

If T: FromZeros, then unsafe code may assume that it is sound to produce a T whose bytes are all initialized to zero. If a type is marked as FromZeros which violates this contract, it may cause undefined behavior.

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

Provided Methods§

Source

fn zero(&mut self)

Overwrites self with zeros.

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(FromZeros)]
#[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]);

§ Code Generation

This abstraction is safe and cheap, but does not necessarily have zero runtime cost. The codegen you experience in practice will depend on optimization level, the layout of the destination type, and what the compiler can prove about the source.

The below examples illustrate typical codegen for increasingly complex types:

Sized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [u8; 2],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

use zerocopy::*;

#[path = "formats/coco_static_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_zero_static_size(source: &mut format::LocoPacket) {
   source.zero()
}

Assembly

bench_zero_static_size:
   mov word ptr [rdi + 4], 0
   mov dword ptr [rdi], 0
   ret

Machine Code Analysis

Iterations:        100
Instructions:      300
Total Cycles:      203
Total uOps:        300

Dispatch Width:    4
uOps Per Cycle:    1.48
IPC:               1.48
Block RThroughput: 2.0


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     1.00           *            mov	word ptr [rdi + 4], 0
1      1     1.00           *            mov	dword ptr [rdi], 0
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -      -      -     2.00   1.00   1.00   1.00   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -      -      -     1.00    -      -     1.00   mov	word ptr [rdi + 4], 0
-      -      -      -     1.00    -     1.00    -     mov	dword ptr [rdi], 0
-      -      -      -      -     1.00    -      -     ret

Unsized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes, SplitAt)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [[u8; 2]],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

use zerocopy::*;

#[path = "formats/coco_dynamic_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_zero_dynamic_size(source: &mut format::LocoPacket) {
   source.zero()
}

Assembly

bench_zero_dynamic_size:
   lea rdx, [2*rsi + 5]
   and rdx, -2
   xor esi, esi
   jmp qword ptr [rip + memset@GOTPCREL]

Machine Code Analysis

Iterations:        100
Instructions:      400
Total Cycles:      142
Total uOps:        500

Dispatch Width:    4
uOps Per Cycle:    3.52
IPC:               2.82
Block RThroughput: 1.3


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.50                        lea	rdx, [2*rsi + 5]
1      1     0.33                        and	rdx, -2
1      0     0.25                        xor	esi, esi
2      6     1.00    *                   jmp	qword ptr [rip + memset@GOTPCREL]


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     0.99   1.00    -     1.01   0.50   0.50   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.99   0.01    -      -      -      -     lea	rdx, [2*rsi + 5]
-      -      -     0.99    -     0.01    -      -     and	rdx, -2
-      -      -      -      -      -      -      -     xor	esi, esi
-      -      -      -      -     1.00   0.50   0.50   jmp	qword ptr [rip + memset@GOTPCREL]

Dynamically Padded

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

#[derive(FromBytes, KnownLayout, Immutable, SplitAt)]
#[repr(C, align(4))]
pub struct Packet<Magic> {
   magic_number: Magic,
   milk: u8,
   mug_size: u8,
   temperature: [u8; 5],
   marshmallows: [[u8; 3]],
}

/// A packet begining with the magic number `0xC0C0`.
pub type CocoPacket = Packet<C0C0>;

/// A packet beginning with any two initialized bytes.
pub type LocoPacket = Packet<[u8; 2]>;

Benchmark

use zerocopy::*;

#[path = "formats/coco_dynamic_padding.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_zero_dynamic_padding(source: &mut format::LocoPacket) {
   source.zero()
}

Assembly

bench_zero_dynamic_padding:
   lea rax, [rsi + 2*rsi]
   movabs rdx, 9223372036854775804
   and rdx, rax
   add rdx, 12
   xor esi, esi
   jmp qword ptr [rip + memset@GOTPCREL]

Machine Code Analysis

Iterations:        100
Instructions:      600
Total Cycles:      209
Total uOps:        700

Dispatch Width:    4
uOps Per Cycle:    3.35
IPC:               2.87
Block RThroughput: 1.8


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.50                        lea	rax, [rsi + 2*rsi]
1      1     0.33                        movabs	rdx, 9223372036854775804
1      1     0.33                        and	rdx, rax
1      1     0.33                        add	rdx, 12
1      0     0.25                        xor	esi, esi
2      6     1.00    *                   jmp	qword ptr [rip + memset@GOTPCREL]


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     1.66   1.66    -     1.68   0.50   0.50   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.33   0.67    -      -      -      -     lea	rax, [rsi + 2*rsi]
-      -     0.98    -      -     0.02    -      -     movabs	rdx, 9223372036854775804
-      -     0.01   0.66    -     0.33    -      -     and	rdx, rax
-      -     0.34   0.33    -     0.33    -      -     add	rdx, 12
-      -      -      -      -      -      -      -     xor	esi, esi
-      -      -      -      -     1.00   0.50   0.50   jmp	qword ptr [rip + memset@GOTPCREL]

Source

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

Creates an instance of Self from zeroed bytes.

§Examples

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

let header: PacketHeader = FromZeros::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]);

§ Code Generation

This abstraction is safe and cheap, but does not necessarily have zero runtime cost. The codegen you experience in practice will depend on optimization level, the layout of the destination type, and what the compiler can prove about the source.

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [u8; 2],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

use zerocopy::*;

#[path = "formats/coco_static_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_new_zeroed() -> format::LocoPacket {
   FromZeros::new_zeroed()
}

Assembly

bench_new_zeroed:
   xor eax, eax
   ret

Machine Code Analysis

Iterations:        100
Instructions:      200
Total Cycles:      103
Total uOps:        200

Dispatch Width:    4
uOps Per Cycle:    1.94
IPC:               1.94
Block RThroughput: 1.0


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      0     0.25                        xor	eax, eax
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -      -      -      -     1.00    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -      -      -     1.00    -      -     ret

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.

Trait FromZeros Copy item path

§Warning: Padding bytes

§Implementation

§Safety

Provided Methods§

fn zero(&mut self)

§Examples

§ Code Generation

Sized

Format

Benchmark

Assembly

Machine Code Analysis

Unsized

Format

Benchmark

Assembly

Machine Code Analysis

Dynamically Padded

Format

Benchmark

Assembly

Machine Code Analysis

fn new_zeroed() -> Selfwhere Self: Sized,

§Examples

§ Code Generation

Format

Benchmark

Assembly

Machine Code Analysis

Dyn Compatibility§

Implementations on Foreign Types§

impl FromZeros for Option<NonZeroI8>

impl FromZeros for Option<NonZeroI16>

impl FromZeros for Option<NonZeroI32>

impl FromZeros for Option<NonZeroI64>

impl FromZeros for Option<NonZeroI128>

impl FromZeros for Option<NonZeroIsize>

impl FromZeros for Option<NonZeroU8>

impl FromZeros for Option<NonZeroU16>

impl FromZeros for Option<NonZeroU32>

impl FromZeros for Option<NonZeroU64>

impl FromZeros for Option<NonZeroU128>

impl FromZeros for Option<NonZeroUsize>

impl FromZeros for bool

impl FromZeros for char

impl FromZeros for f32

impl FromZeros for f64

impl FromZeros for i8

impl FromZeros for i16

impl FromZeros for i32

impl FromZeros for i64

impl FromZeros for i128

impl FromZeros for isize

impl FromZeros for str

impl FromZeros for u8

impl FromZeros for u16

impl FromZeros for u32

impl FromZeros for u64

impl FromZeros for u128

impl FromZeros for ()

impl FromZeros for usize

impl FromZeros for __m128

impl FromZeros for __m128d

impl FromZeros for __m128i

impl FromZeros for __m256

impl FromZeros for __m256d

impl FromZeros for __m256i

impl FromZeros for __m512

impl FromZeros for __m512bh

impl FromZeros for __m512d

impl FromZeros for __m512i

impl FromZeros for AtomicBool

impl FromZeros for AtomicI8

impl FromZeros for AtomicI16

impl FromZeros for AtomicI32

impl FromZeros for AtomicI64

impl FromZeros for AtomicIsize

impl FromZeros for AtomicU8

impl FromZeros for AtomicU16

Trait FromZeros

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