Macro try_transmute

Source

macro_rules! try_transmute {
    ($e:expr) => { ... };
}

Expand description

Conditionally transmutes a value of one type to a value of another type of the same size.

This macro behaves like an invocation of this function:

fn try_transmute<Src, Dst>(src: Src) -> Result<Dst, ValidityError<Src, Dst>>
where
    Src: IntoBytes,
    Dst: TryFromBytes,
    size_of::<Src>() == size_of::<Dst>(),
{
    ...
}

However, unlike a function, this macro can only be invoked when the types of Src and Dst are completely concrete. The types Src and Dst are inferred from the calling context; they cannot be explicitly specified in the macro invocation.

Note that the Src produced by the expression $e will not be dropped. Semantically, its bits will be copied into a new value of type Dst, the original Src will be forgotten, and the value of type Dst will be returned.

§Examples

// 0u8 → bool = false
assert_eq!(try_transmute!(0u8), Ok(false));

// 1u8 → bool = true
 assert_eq!(try_transmute!(1u8), Ok(true));

// 2u8 → bool = error
assert!(matches!(
    try_transmute!(2u8),
    Result::<bool, _>::Err(ValidityError { .. })
));

§ 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)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

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

/// 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::Unalign;
use zerocopy_derive::*;

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

#[derive(IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct MinimalViableSource {
   bytes: [u8; 6],
}

#[unsafe(no_mangle)]
fn bench_try_transmute(source: MinimalViableSource) -> Option<Unalign<format::CocoPacket>> {
   zerocopy::try_transmute!(source).ok()
}

Assembly

bench_try_transmute:
   movzx ecx, di
   xor eax, eax
   cmp ecx, 49344
   sete al
   and rdi, -65536
   xor rax, 49345
   or rax, rdi
   ret

Machine Code Analysis

Iterations:        100
Instructions:      800
Total Cycles:      238
Total uOps:        800

Dispatch Width:    4
uOps Per Cycle:    3.36
IPC:               3.36
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     0.33                        movzx	ecx, di
1      0     0.25                        xor	eax, eax
1      1     0.33                        cmp	ecx, 49344
1      1     0.50                        sete	al
1      1     0.33                        and	rdi, -65536
1      1     0.33                        xor	rax, 49345
1      1     0.33                        or	rax, rdi
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.33   2.33    -     2.34    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.32   0.67    -     0.01    -      -     movzx	ecx, di
-      -      -      -      -      -      -      -     xor	eax, eax
-      -     0.33   0.67    -      -      -      -     cmp	ecx, 49344
-      -     1.00    -      -      -      -      -     sete	al
-      -     0.67   0.33    -      -      -      -     and	rdi, -65536
-      -      -     0.66    -     0.34    -      -     xor	rax, 49345
-      -     0.01    -      -     0.99    -      -     or	rax, rdi
-      -      -      -      -     1.00    -      -     ret

try_transmute