bytes.h File Reference

Versatile byte buffer with small-buffer optimisation, ownership semantics and 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
	Versatile 128-byte byte buffer with SBO, five ownership modes and compression helpers. More...

Namespaces
namespace	vlink

Detailed Description

Versatile byte buffer with small-buffer optimisation, ownership semantics and compression.

Bytes is the primary binary data carrier in VLink. Every message serialised or received by a publisher/subscriber is wrapped in a Bytes object. The class is designed to minimise heap allocations on the hot path:

• Buffers up to kStackSize (96) bytes are stored entirely within the object's inline stack_data_ array (small-buffer optimisation / SBO).
• Larger buffers are allocated from an optional pmr::synchronized_pool_resource (Linux only when __cpp_lib_memory_resource is available), or from the system heap via bytes_malloc() / bytes_free().
• The total object size is exactly 128 bytes regardless of content.

Ownership model:

Factory method	Owns memory	On copy	Use case
Bytes::create()	Yes	Deep copy	Fresh allocation
Bytes::shallow_copy()	No	Ptr alias	Zero-copy wrapping of extern buf
Bytes::deep_copy()	Yes	Deep copy	Owned copy of extern buf
Bytes::loan_internal()	No (loaned)	Ptr alias	Iceoryx zero-copy loan
Bytes::shallow_copy_ptr()	No	Ptr alias	Wrap opaque pointer (size == 0)

Compression support (LZAV):

• compress_data() appends a 4-byte header magic and a 4-byte footer magic around the LZAV compressed payload, enabling is_compress_data() to detect compressed buffers.
• uncompress_data() strips the header/footer and decompresses; optionally validates the magic bytes first.

Utility helpers:

• Base-64 encode/decode (encode_to_base64 / decode_from_base64)
• CRC-32 checksum (get_crc_32)
• Byte-order reversal (reverse_order)
• Hex-string conversion (convert_to_hex_str)
• User-input parsing from hex/binary string literals (from_user_input)

Note

• The offset_ field reserves a prefix region inside the allocated buffer. data() returns real_data() + offset(). This allows transport layers to prepend headers in-place without re-allocation.
• is_loaned() is set by loan_internal(), which is used exclusively for iceoryx zero-copy payloads that must not be freed by VLink.
• is_ptr() returns true when size == 0 and offset == 0 and the object is not an owner, meaning the buffer holds only an opaque pointer created via shallow_copy_ptr().
• init_memory_pool() and release_memory_pool() must be called explicitly at application startup/shutdown if the memory pool is desired. They are no-ops when the pool is unavailable.

Example

// SBO path (no heap allocation):
auto buf = vlink::Bytes::create(64);
std::memcpy(buf.data(), payload, 64);
 
// Zero-copy shallow wrap:
auto view = vlink::Bytes::shallow_copy(ext_ptr, ext_size);
 
// Compression:
auto compressed = vlink::Bytes::compress_data(buf.data(), buf.size());
if (vlink::Bytes::is_compress_data(compressed.data(), compressed.size())) {
  auto original = vlink::Bytes::uncompress_data(compressed.data(), compressed.size());
}