TensorPool, Image & PointCloud API

HORUS provides zero-copy shared memory pools for large data: camera frames, lidar scans, and neural network tensors. Data lives in a pre-allocated SHM region and is shared by reference between the processes that open the same pool -- no serialization, no copies.

#include <horus/pool.hpp>

Architecture

The pool system has four classes arranged in a hierarchy:

Image and PointCloud are convenience wrappers over pool-backed memory: the pixel and point data live in the pool's SHM region rather than inside the object. All three release their slot automatically when destroyed; Tensor additionally exposes release() to return the slot early -- see release() below.

TensorPool

A fixed-size shared memory region divided into allocation slots.

Constructor

horus::TensorPool pool(
    uint32_t pool_id,         // unique pool identifier
    size_t   pool_size_bytes, // total SHM region size
    size_t   max_slots        // maximum concurrent allocations
);

Parameters

Example

// 16 MB pool with up to 64 concurrent allocations
auto pool = horus::TensorPool(1, 16 * 1024 * 1024, 64);

stats()

Returns current pool utilization.

TensorPool::Stats stats() const;

Returns a Stats struct:

auto s = pool.stats();
horus::log::info("pool", ("used: " + std::to_string(s.used_bytes) +
    " free: " + std::to_string(s.free_bytes)).c_str());

Ownership and Validity

TensorPool is move-only -- copy construction and copy assignment are deleted. Use explicit operator bool() to check if the pool handle is valid:

auto pool2 = std::move(pool);  // OK -- transfers ownership
if (!pool2) {
    horus::log::error("init", "Failed to create tensor pool");
}

Tensor

A raw N-dimensional array allocated from a TensorPool.

Constructor

horus::Tensor tensor(
    const TensorPool& pool,     // pool to allocate from
    const uint64_t*   shape,    // dimension sizes array
    size_t            ndim,     // number of dimensions
    Dtype             dtype     // element data type
);

Parameters

Methods

Dtype Enum

Element data types for tensors.

enum class Dtype : uint8_t {
    F32,   // 32-bit float
    F64,   // 64-bit float
    U8,    // unsigned 8-bit integer
    I32,   // signed 32-bit integer
};

Image

A camera frame with width, height, and pixel encoding, backed by pool memory.

Constructor

horus::Image img(
    const TensorPool& pool,
    uint32_t          width,
    uint32_t          height,
    Encoding          enc = Encoding::Rgb8  // optional, defaults to RGB8
);

Parameters

Methods

Encoding Enum

Pixel encoding formats for images.

enum class Encoding : uint8_t {
    Rgb8,    // 3 bytes per pixel: red, green, blue
    Rgba8,   // 4 bytes per pixel: red, green, blue, alpha
    Gray8,   // 1 byte per pixel: grayscale
    Bgr8,    // 3 bytes per pixel: blue, green, red (OpenCV default)
};

PointCloud

A lidar scan or 3D point set, backed by pool memory.

Constructor

horus::PointCloud pc(
    const TensorPool& pool,
    uint32_t          num_points,
    uint32_t          fields_per_point
);

Parameters

Methods

Common Field Layouts

Example: Camera Frame Allocation

A camera node that reserves frame buffers in pool-backed shared memory.

#include <horus/node.hpp>
#include <horus/pool.hpp>

auto pool = horus::TensorPool(1, 32 * 1024 * 1024, 32);

// Inside tick():
auto frame = horus::Image(pool, 1280, 720, horus::Encoding::Rgb8);
if (frame) {
    // Frame memory is now reserved in the pool's SHM region.
    // data_size() = 1280 * 720 * 3 = 2,764,800 bytes
}

There is no publish step here: Publisher<T> / Subscriber<T> are specialized only for the fixed-size horus::msg:: POD types, so sched.advertise<horus::Image>(...) does not compile. From C++, pool-backed types are allocated inside the processes that open the pool, and only Tensor exposes a data pointer (data()) -- Image and PointCloud expose metadata only. See Topic for the message types that can be published.

Example: Neural Network Tensor

#include <horus/pool.hpp>

auto pool = horus::TensorPool(2, 64 * 1024 * 1024, 16);

// Allocate a [1, 3, 224, 224] input tensor for a vision model
uint64_t shape[] = {1, 3, 224, 224};
auto input = horus::Tensor(pool, shape, 4, horus::Dtype::F32);

if (input) {
    float* data = reinterpret_cast<float*>(input.data());
    // Fill with preprocessed image data...
    // nbytes() = 1 * 3 * 224 * 224 * 4 = 602,112 bytes
    input.release();  // optional -- returns the slot early; ~Tensor() also releases it
}

Pool Sizing Guidelines

Overallocating pool size is not free. At construction HORUS pre-faults the pool's data region with madvise(MADV_POPULATE_WRITE), up to HORUS_SHM_PREFAULT_MAX_BYTES (64 MiB by default), which commits those pages to physical memory. A pool of 64 MB or less -- every size in the table above -- is therefore fully resident the moment it is created; only the part of a larger pool beyond the cap stays uncommitted. Set HORUS_SHM_PREFAULT=0 to disable pre-faulting, or lower HORUS_SHM_PREFAULT_MAX_BYTES, if you would rather pay the page faults in the control loop. Underallocating max_slots causes allocation failures when the pipeline is full.