Trait FromZeros

pub unsafe trait FromZeros: TryFromBytes

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.:

# use zerocopy_derive::{FromZeros, Immutable};
#[derive(FromZeros)]
struct MyStruct {
# /*
    ...
# */
}

#[derive(FromZeros)]
#[repr(u8)]
enum MyEnum {
#   Variant0,
# /*
    ...
# */
}

#[derive(FromZeros, Immutable)]
union MyUnion {
#   variant: u8,
# /*
    ...
# */
}

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

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

# use zerocopy::FromZeros;
# use zerocopy_derive::*;
#
#[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]


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

Creates an instance of Self from zeroed bytes.

Examples

# use zerocopy::FromZeros;
# use zerocopy_derive::*;
#
#[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

Implementors