C++ Adapter

Use Zinc from C++ with a header-only RAII wrapper

The C++ adapter is a header-only library that wraps the C ABI in RAII types and std::span. No separate build step is required.

Installation

Copy zinc.hpp into your project:

cp adapters/cpp/include/zinc.hpp include/zinc.h /your/project/include/

Link against libzinc_core at build time:

# Linux
g++ -std=c++20 -o myapp myapp.cpp -lzinc_core -L/path/to/target/release

# macOS
clang++ -std=c++20 -o myapp myapp.cpp -lzinc_core -L/path/to/target/release

SharedRegion

#include "zinc.hpp"

using namespace zinc;

create

auto region = SharedRegion::create("my-data", 16384);

Creates a new region. Throws std::system_error on failure. The error code maps to the negated Zinc error code.

open

auto region = SharedRegion::open("my-data");

Opens an existing region.

bytes

Returns a std::span<std::byte> backed by the shared memory mapping. No copying occurs.

auto bytes = region.bytes();
*reinterpret_cast<float*>(bytes.data()) = 3.14f;
auto val = *reinterpret_cast<const float*>(bytes.data());

A const overload is available for read-only access:

const auto& const_region = region;
auto read_only = const_region.bytes();

capacity

auto cap = region.capacity();

notify

region.notify();

wait

bool ok = region.wait(1000);

Returns true on notification, false on timeout.

RAII semantics

SharedRegion is move-only. It cannot be copied. The handle closes automatically when it goes out of scope.

{
    auto region = SharedRegion::create("temp", 16384);
    // region is active here
}
// region is automatically closed and (if owner) unlinked

// Move ownership
auto a = SharedRegion::open("my-data");
auto b = std::move(a);
// 'a' is now empty, 'b' owns the handle

Complete example

#include "zinc.hpp"
#include <cstring>
#include <iostream>

int main() {
    auto writer = zinc::SharedRegion::create("cpp-channel", 16384);
    uint64_t value = 42;
    std::memcpy(writer.bytes().data(), &value, sizeof(value));
    writer.notify();

    auto reader = zinc::SharedRegion::open("cpp-channel");
    if (reader.wait(5000)) {
        uint64_t result;
        std::memcpy(&result, reader.bytes().data(), sizeof(result));
        std::cout << result << "\n";
    }
}

This uses two handles in one process. For separate processes, keep the creator running until the reader finishes. Spans must not outlive their region. try_wait() consumes a pending notification without blocking.

Requirements

• C++20 or later (for std::span)
• A C++ compiler that supports std::span on Linux or macOS
• The zinc_core shared library on the library search path at runtime