tensor.h File Reference

Zero-copy N-dimensional dense tensor container with shape, strides, and dtype metadata. More...

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

Include dependency graph for tensor.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

Zero-copy N-dimensional dense tensor container with shape, strides, and dtype metadata.

Tensor is the canonical neural-network input / output message for the VLink autonomous-driving and embodied-intelligence stacks: camera feature maps, point-cloud features, language-model hidden states, action heads, diffusion latents, INT8 quantised activations, and so on. Each tensor carries the element buffer, shape (up to kMaxRank dimensions), strides, dtype, layout label, optional model identifier, optional INT8 quantisation scale / zero point, device hint, plus a 40-byte Header for sequencing.

DType table

Enum	C++ type	Element size
kBool	bool	1
kInt8	int8_t	1
kUint8	uint8_t	1
kInt16	int16_t	2
kUint16	uint16_t	2
kInt32	int32_t	4
kUint32	uint32_t	4
kInt64	int64_t	8
kUint64	uint64_t	8
kFloat16	half	2
kBfloat16	bf16	2
kFloat32	float	4
kFloat64	double	8

Shape diagram

rank: 1..kMaxRank (kMaxRank = 8)
shape  [d0, d1, ..., d{rank-1}]    e.g. NCHW = [N, C, H, W]
strides[s0, s1, ..., s{rank-1}]    elements (not bytes) to step one index
 
Contiguous row-major (computed by set_shape):
    s{rank-1} = 1
    s{i}      = s{i+1} * shape[i+1]
 
Strided view example (slice the C axis of an NCHW tensor):
    shape   = [N, C', H, W]
    strides = [s0, s1, s2, s3]    s1 may exceed H*W to skip slabs

Wire format

Tensor is POD; memcpy serialises the struct plus the element bytes. The sizeof value is locked by static_assert and forms a permanent contract: vlink::zerocopy::* containers have NO forward and NO backward binary compatibility, and every field, including reserved bytes, is wire-locked.

static_assert(sizeof(Tensor) == 248, "Sizeof must be 248 bytes.");

Memory layout

Offset  Size  Field
------  ----  ------------------------------------
     0    40  Header   header
    40     8  uint8_t* data_
    48     8  size_t   size_
    56     8  uint64_t update_time_ns_
    64     8  uint64_t num_elements_
    72    32  char     name_[32]
   104    32  char     model_id_[32]
   136    16  char     layout_[16]
   152    32  uint32_t shape_[kMaxRank]
   184    32  uint32_t strides_[kMaxRank]
   216     4  uint32_t channel_
   220     4  uint32_t freq_
   224     4  uint32_t batch_size_
   228     4  float    quant_scale_
   232     4  int32_t  quant_zero_point_
   236     1  DataType dtype_
   237     1  uint8_t  rank_
   238     1  Device   device_
   239     1  bool     is_owner_
   240     1  uint8_t  element_size_
   241     1  uint8_t  reserved_buf_
   242     2  uint16_t reserved_buf2_
   244     4  uint32_t reserved_buf3_
------  ----  ------------------------------------
 Total   248  bytes (alignas 8)
 
Wire envelope:
[ magic_begin (4) | version (4) | Tensor struct (248) | element bytes (num_elements*element_size) | magic_end (4) ]

Reserved bytes

reserved_buf_, reserved_buf2_, reserved_buf3_ are exposed through get_reserved* helpers and survive clear() and the copy / move helpers. These slots MUST NOT be repurposed by application code: future library revisions may bind them to real fields, silently breaking peers that abused the slot.

Example

vlink::zerocopy::Tensor t;
t.set_name("image");
t.set_layout("NCHW");
t.set_dtype(vlink::zerocopy::Tensor::kFloat32);
uint32_t shape[] = {1, 3, 224, 224};
t.set_shape(shape, 4);
t.create(t.num_elements() * sizeof(float));
 
vlink::Bytes wire;
t >> wire;