bytes.h File Reference

Canonical 128-byte binary payload carrier with inline storage, multi-mode ownership and LZAV compression. More...

#include <cstddef>
#include <cstdint>
#include <cstring>
#include <iostream>
#include <string>
#include <string_view>
#include <vector>
#include "./macros.h"

Include dependency graph for bytes.h:

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

Go to the source code of this file.

Classes
class	vlink::Bytes
	Fixed-size 128-byte buffer holder with SBO, five ownership modes and integrated codecs. More...

Namespaces
	vlink

Detailed Description

Canonical 128-byte binary payload carrier with inline storage, multi-mode ownership and LZAV compression.

Every binary buffer that crosses a VLink boundary (publish, subscribe, RPC argument, field value, proxy snapshot) flows through a vlink::Bytes object. The class fuses five orthogonal concerns into a single fixed-size 128-byte structure: small-buffer optimisation, ownership tagging, loaned-memory tracking, prefix-offset reservation and a compression / encoding utility surface.

Ownership model

Factory	Owns memory	Frees on destroy	Aliases source pointer	Typical caller
Bytes::create	yes	yes	no	Fresh allocation
Bytes::shallow_copy	no	no	yes	Zero-copy view
Bytes::deep_copy	when sized	when sized	no	Detached owned copy
Bytes::loan_internal	no (loaned)	no	yes	Iceoryx zero-copy
Bytes::shallow_copy_ptr	no	no	yes	Opaque pointer wrap

Memory layout (logical)

*  +------------------------------------------------------------------+
*  |                          Bytes (128 B)                           |
*  +-------------------------+-------+----+------+-------+------------+
*  | stack_data_ (96 B SBO)  | owner | ln | off  | size  | capacity   |
*  +-------------------------+-------+----+------+-------+------------+
*                                              |
*                                              | (when size > 96 B)
*                                              v
*                                +--------------------------------+
*                                |  heap buffer from MemoryPool   |
*                                |  [ offset prefix ][ payload ]  |
*                                +--------------------------------+
* 

Compression frame layout

*  byte:    0   1   2   3   4   5   6   7   8                       N-4  N-3  N-2  N-1
*         +---+---+---+---+---+---+---+---+---+ - - - - - - - - - +----+----+----+----+
*  field: | header magic  | original size BE  |  LZAV payload     |  footer magic     |
*         +---+---+---+---+---+---+---+---+---+ - - - - - - - - - +----+----+----+----+
*           17  49  B2  6F                                            A7   05   ED   71
* 

Buffers below or equal to kStackSize (96 bytes) reside entirely in stack_data_; only larger payloads pull from MemoryPool::global_instance() through bytes_malloc. The total object footprint is fixed at 128 bytes regardless of payload size. An offset prefix reserves space at the head of the buffer so transport adapters can prepend protocol headers without realloc; data() returns real_data() + offset().

Example

vlink::Bytes a = vlink::Bytes::create(64);            // SBO path, no heap allocation
std::memcpy(a.data(), payload, a.size());
 
vlink::Bytes view = vlink::Bytes::shallow_copy(ext, ext_size);   // zero-copy alias
 
auto packed = vlink::Bytes::compress_data(a.data(), a.size());
if (vlink::Bytes::is_compress_data(packed.data(), packed.size())) {
  vlink::Bytes plain = vlink::Bytes::uncompress_data(packed.data(), packed.size());
}
 
const uint32_t crc = vlink::Bytes::get_crc_32(a);
const std::string base64 = vlink::Bytes::encode_to_base64(a);
vlink::Bytes round_trip = vlink::Bytes::decode_from_base64(base64);