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§
Sourcefn zero(&mut self)
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]
Sourcefn new_zeroed() -> Selfwhere
Self: Sized,
fn new_zeroed() -> Selfwhere
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.