raw_data.h File Reference

Generic zero-copy byte-buffer container with a Header prefix. More...

#include <cstdint>
#include "../base/bytes.h"
#include "./header.h"

Include dependency graph for raw_data.h:

Go to the source code of this file.

Namespaces
	vlink
	vlink::zerocopy

Functions
struct	vlink::zerocopy::VLINK_EXPORT_AND_ALIGNED (8) AudioFrame final

Detailed Description

Generic zero-copy byte-buffer container with a Header prefix.

RawData is the most lightweight container in the vlink::zerocopy family. It pairs an opaque payload (any application-defined byte blob: Protobuf wire bytes, FlatBuffer tables, compressed frames, encrypted CAN snapshots, ...) with a 40-byte Header so that consumers can sequence and time-stamp the payload without parsing it. Use RawData whenever the payload schema is opaque to VLink, or when a higher-level layer wraps its own framing on top.

Ownership mode	How to create	Frees on destruction
Owned	create(size)	Yes
Borrowed	shallow_copy(ptr, size)	No
Deserialised	operator<<(bytes)	No (borrows bytes)

Wire format

RawData is POD; the canonical serialiser is memcpy(). The sizeof value is locked by static_assert and forms a permanent binary contract: VLink zero-copy containers have NO forward and NO backward compatibility across versions, and every field including the reserved slot is part of that contract.

static_assert(sizeof(RawData) == 64, "Sizeof must be 64 bytes.");

Memory layout

Offset  Size  Field
------  -----  --------------------------------
     0     40  Header header
    40      8  uint8_t* data_
    48      8  size_t   size_
    56      1  bool     is_owner_
    57      1  (padding)
    58      2  uint16_t reserved_buf_
    60      4  (tail padding to align(8))
------  -----  --------------------------------
 Total     64  bytes (alignas 8)
 
Wire envelope:
[ magic_begin (4) | version (4) | RawData struct (64) | payload (size_) | magic_end (4) ]

Reserved bytes

reserved_buf_ travels through the wire format unchanged. It is exposed via get_reserved() so applications can stash a flag or minor sub-type id without inflating the struct, but the slot must not be redefined later – doing so would silently break any peer that still expects the old meaning.

Example

vlink::zerocopy::RawData rd;
rd.header.seq      = ++seq;
rd.header.time_pub = vlink::time_ns();
rd.create(payload.size());
std::memcpy(const_cast<uint8_t*>(rd.data()), payload.data(), payload.size());
 
vlink::Bytes wire;
rd >> wire;
 
vlink::zerocopy::RawData rx;
rx << wire;