C++ component API

A C++ Pipelogic component is component.yml plus src/main.cpp. The YAML declares the platform-facing inputs, outputs, config, files, and build settings; main.cpp contains the worker logic that runs in the component binary. The build system compiles that entrypoint and ships it inside the deployment.

This page is the index for the C++ component API. The detailed pages live under component-api/cpp/ — class description, factory-typed components, stateful patterns, error handling, headers, and the full type reference.

For C++ components (language: cpp), the only file you author is src/main.cpp. There is no xmake.lua in your component directory — the build base owns the build script. The compile stage treats main.cpp as the entry point, links it against the C++ ML SDK runtime + your declared xmake_packages:, and produces the component binary that the platform runs in a container.

This index lists every doc under component-api/cpp/ and what each covers. Read in order if you've never written a C++ component; jump to a specific page when you know which shape/topic you're after.

Required reading order

component-api/cpp/types — what Message, Object<T>, String, List<T>, Tuple<T...> mean. Every other doc assumes you know these.
component-api/cpp/headers — header catalog. Which #include brings what.
component-api/cpp/config — parse_config, read_config, mutable parameters.
Pick the component shape that matches your component.yml (next section).
component-api/cpp/errors — exceptions, log conventions.

API references

When you need the exact signature for every public member of every type, not the narrative explanation:

Types reference — every name in types.hpp: atomic tags, List/Tuple/Union/Record/Named, the concepts:: namespace, Type, TypeManager, all create_* factories.
Object reference — every public member of Object<T>, Reference<T>, ConstReference<T> across all 8 underlying kinds, plus the lifetime / aliasing invariants.

The narrative docs above are still the right entry point — these references exist for "what's the exact signature of mutable_get on a static Reference<Record>?" questions.

Component shapes

Pick the shape based on how many inputs you take, whether they map 1-to-1, and whether you need state or pull control:

Use this shape	When
`component-api/cpp/single-io`	One input, one output, stateless. The default and simplest case.
`component-api/cpp/multi-input-positional`	Multiple inputs that always arrive together (1-tick-per-tick), each one a `Message` arg.
`component-api/cpp/vector-io`	Multiple inputs/outputs taken as a `std::vector<Message>` (variadic / generic).
`component-api/cpp/stateful`	You need state across messages (counters, EMA, session map, accumulator).
`component-api/cpp/factory-typed`	The component shape depends on the type that gets connected (generics like `t`).
`component-api/cpp/class-description`	You need full pull-control (rate limiters, batchers, async streaming, lifecycle hooks).

Skeleton

Every main.cpp starts and ends like this:

#include "pipelogic/pipelogic.hpp"

using namespace ppl;

// ... your worker function(s) ...

PIPELOGIC_MAIN() {
  run(<your_function>);
  return EXIT_SUCCESS;
}

PIPELOGIC_MAIN() is a macro that expands to int main(int, char**) plus the runtime bootstrap. You never write int main yourself. The sole call inside the macro body is run(...) — the variant that matches your component shape (every shape doc shows the exact form).

return EXIT_SUCCESS; is mandatory — the macro requires the body to return.

Build configuration

build_system: in component.yml selects the compile + runtime base (see concepts/build-systems). For C++ components:

build_system	Brings
`2`	C++ ML SDK toolchain and runtime, no extra ML libs.
`2-ml`	`2` + OpenCV, the C++ ML SDK's ML headers, common inference deps.

For libraries beyond the base, list them under xmake_packages: in component.yml:

xmake_packages:
  - libcurl
  - nlohmann_json

Use the structured form when the xmake package needs configs:

xmake_packages:
  - require: arrow 7.0.0
    package: arrow
    configs:
      parquet: true
      csv: false
      snappy: true
      zstd: true

require is the exact add_requires(...) spec. package is the name passed to add_packages(...); omit it when the inferred name is correct. configs maps directly to xmake {configs = {...}}.

The build resolves these from xmake's package registry — you don't write any build script.