header.h File Reference

Fixed-size timestamp and sequencing prefix embedded by every VLink zero-copy container. More...

#include <cstdint>
#include <cstring>
#include <string_view>
#include "../base/macros.h"
#include "../version.h"

Include dependency graph for header.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Namespaces
	vlink
	vlink::zerocopy

Functions
constexpr uint32_t	vlink::zerocopy::version_major (uint32_t version) noexcept
	Extracts the major component from an encoded zero-copy wire version. More...
struct	vlink::zerocopy::VLINK_EXPORT_AND_ALIGNED (8) AudioFrame final

Variables
constexpr uint32_t	vlink::zerocopy::kWireVersion
	Encoded VLink library version stamped into every zero-copy wire envelope. More...

Detailed Description

Fixed-size timestamp and sequencing prefix embedded by every VLink zero-copy container.

Header is the foundation of the vlink::zerocopy family. Every other zero-copy container (RawData, CameraFrame, AudioFrame, PointCloud, Tensor, OccupancyGrid, ObjectArray) embeds a Header as its first public member so that consumers always know where to read the per-frame seq, frame_id, and dual timestamps regardless of the payload type.

Concern	Field	Purpose
Identity	frame_id	Source sensor / coordinate-frame label (16 char)
Sequencing	seq	Monotonically increasing per-publisher counter
Acquisition	time_meas	Time the producer captured the data (ns)
Publication	time_pub	Time the producer dispatched the message (ns)

Wire format

The struct is POD; memcpy() over its 40 bytes is the canonical serialiser. The sizeof() value is locked by static_assert and forms a permanent contract: the vlink::zerocopy::* containers have no forward and no backward binary compatibility. Reserved bytes count as part of the contract too.

static_assert(sizeof(Header) == 40, "Sizeof must be 40 bytes.");

Memory layout

Offset  Size  Field
------  ----  ------------------
     0    16  frame_id[16]
    16     4  seq
    20     4  reserved
    24     8  time_meas
    32     8  time_pub
------  ----  ------------------
 Total    40  bytes (alignas 8)

Reserved bytes

The 4-byte reserved slot at offset 20 is part of the wire contract. It MUST NOT be repurposed by application code: reading it back after future library upgrades would silently corrupt data. Treat the byte as opaque.

Example

vlink::zerocopy::RawData raw;
std::strncpy(raw.header.frame_id, "lidar_top", sizeof(raw.header.frame_id) - 1);
raw.header.seq       = next_seq++;
raw.header.time_meas = sensor_ns;
raw.header.time_pub  = vlink::time_ns();
 
auto label = raw.header.frame_id_view();