--- title: "API reference" sidebar_label: "Overview" description: "The ClikaRT public C++ API, by namespace and class." --- The public API of ClikaRT is the `ClikaRT::` namespace, declared by the headers under `ClikaRT/`. Include `ClikaRT/clika_rt.h` for everything, or the individual headers named on each page. ## Namespaces | Name | Description | | --- | --- | | [`ClikaRT::cli`](./ClikaRT/cli/index.md) | | | [`ClikaRT::device`](ClikaRT/device-namespace/index.md) | | | [`ClikaRT::dtype`](./ClikaRT/dtype/index.md) | The dtype-system helpers: classification predicates, size arithmetic, and the readable name. [`DataType`](./index.md#DataType) itself stays at [`ClikaRT`](./index.md)`::` (the one name every signature spells); everything ABOUT a dtype lives here. | | [`ClikaRT::encoding`](./ClikaRT/encoding/index.md) | | | [`ClikaRT::env`](./ClikaRT/env/index.md) | | | [`ClikaRT::graph`](./ClikaRT/graph/index.md) | | | [`ClikaRT::http`](./ClikaRT/http/index.md) | | | [`ClikaRT::io`](./ClikaRT/io/index.md) | | | [`ClikaRT::json`](./ClikaRT/json/index.md) | | | [`ClikaRT::logging`](./ClikaRT/logging/index.md) | | | [`ClikaRT::nn`](./ClikaRT/nn/index.md) | | | [`ClikaRT::ops`](./ClikaRT/ops/index.md) | | | [`ClikaRT::placement`](./ClikaRT/placement/index.md) | | | [`ClikaRT::platform`](./ClikaRT/platform/index.md) | | | [`ClikaRT::processor`](./ClikaRT/processor/index.md) | | | [`ClikaRT::progress`](./ClikaRT/progress/index.md) | | | [`ClikaRT::quant`](./ClikaRT/quant/index.md) | The quantized-checkpoint import taxonomy: the parsed `quantization_config` facts and the routing enums the split factories consume. | | [`ClikaRT::random`](./ClikaRT/random/index.md) | | | [`ClikaRT::regex`](./ClikaRT/regex/index.md) | | | [`ClikaRT::runtime`](./ClikaRT/runtime/index.md) | | | [`ClikaRT::spec`](./ClikaRT/spec/index.md) | | | [`ClikaRT::tables`](./ClikaRT/tables/index.md) | | | [`ClikaRT::threading`](./ClikaRT/threading/index.md) | | | [`ClikaRT::tokenizer`](./ClikaRT/tokenizer/index.md) | | ## Classes | Name | Description | | --- | --- | | [`Device`](./ClikaRT/Device.md) | A compute device: a backend API plus a device index (e.g. the `1` in CUDA device 1). Default-constructs to the whole-machine host CPU. | | [`EagerScope`](./ClikaRT/EagerScope.md) | While alive, forces EAGER execution on the calling thread: every op runs its kernel and produces a real value before dispatch returns, even when nested inside a [`TracingScope`](./ClikaRT/TracingScope.md). Use it to guard a region that must compute concrete values (a metric, a running average, a control-flow decision read back to the host) so a caller who wrapped the surrounding code in a [`TracingScope`](./ClikaRT/TracingScope.md) cannot turn those ops into un-materialized placeholders. Outside any scope execution is already eager, so this is a no-op there. Non-copyable, non-movable. | | [`Error`](./ClikaRT/Error.md) | Thrown by the throwing API overloads and by [Result::value\_or\_throw()](./ClikaRT/Result.md#value_or_throw). | | [`FakeTensor`](./ClikaRT/FakeTensor.md) | A value type (no out-of-line surface): it holds a `vector<`[`spec::SymInt`](./ClikaRT/spec/SymInt.md)`>`, a dtype, a copyable [`Stream`](./ClikaRT/Stream.md), and a flag, all ABI-stable, so it crosses by layout. | | [`NamedTensors`](./ClikaRT/NamedTensors.md) | An insertion-agnostic `name → `[`Tensor`](./ClikaRT/Tensor.md) map. Copyable and movable (a copy shares each entry's storage; the tensors are refcount handles). A moved-from [NamedTensors](./ClikaRT/NamedTensors.md) is empty: every read answers empty / false / 0, and [`set`](./ClikaRT/NamedTensors.md#set) fills it again (a dict moved into `load_state_dict` stays a usable object). | | [`ProfileSession`](./ClikaRT/ProfileSession.md) | A profiling session: start one or more captures, then export the results. Move-only. The session must outlive any in-flight async work it captured (workers that finish after a capture ends still record into it). | | [`ProfileSummary`](./ClikaRT/ProfileSummary.md) | The counters a session accumulated, as plain values: the typed form of [`ProfileSession::summary_text()`](./ClikaRT/ProfileSession.md#summary_text) and of the `summary` object in `report.json`, field for field, so a consumer reads numbers instead of parsing text. Durations are nanoseconds; counts are events recorded inside the session's captures. | | [`QTensor`](./ClikaRT/QTensor.md) | A quantized weight, viewed with its scheme. A value type over a refcounted payload handle; copying a [`QTensor`](./ClikaRT/QTensor.md) never copies weight bytes. | | [`Result`](./ClikaRT/Result.md) | Holds either a success value of type T or a ([Status](./index.md#Status), message) failure. Move-only. Check [ok()](./ClikaRT/Result.md#ok) before reading [value()](./ClikaRT/Result.md#value), or use [value\_or\_throw()](./ClikaRT/Result.md#value_or_throw). \[\[nodiscard\]\]: a call that returns a [`Result`](./ClikaRT/Result.md) and discards it swallows the failure it may carry; the compiler warns at such a site; consume it ([`unwrap`](./index.md#unwrap), [`CLIKART_CHECK`](./index.md#CLIKART_CHECK), a named read) or discard deliberately with a `(void)` cast. | | [`Result\`](./ClikaRT/Result.void.md) | Outcome of a fallible operation that yields no value on success (e.g. registering a route, writing a file). Check [`ok()`](./ClikaRT/Result.void.md#ok), or call [`value_or_throw()`](./ClikaRT/Result.void.md#value_or_throw) to raise [`ClikaRT::Error`](./ClikaRT/Error.md) on failure in your own TU. \[\[nodiscard\]\]: a statement-position effect call that ignores its result swallows the failure; the compiler warns; consume it ([`CLIKART_CHECK`](./index.md#CLIKART_CHECK), [`unwrap`](./index.md#unwrap), a named read) or discard deliberately with a `(void)` cast. | | [`Scalar`](./ClikaRT/Scalar.md) | A scalar operand that keeps its KIND across the boundary: a bool, an integer (any width, stays integral), or a double. What it buys over a bare double parameter: an integer scalar against an integer tensor stays in the integer domain (`ops::sub(2, int64_tensor)` is Int64, exact at any magnitude), where a double would force weak-float promotion. Every ctor is implicit on purpose. Pass the bare literal. Distinct from [`ScalarOrTensor`](./ClikaRT/ScalarOrTensor.md): a [`Scalar`](./ClikaRT/Scalar.md) never carries a tensor, which is what keeps a two-tensor call (`ops::add(a, b)`) unambiguous against the tensor-first overloads. | | [`ScalarOrTensor`](./ClikaRT/ScalarOrTensor.md) | A ClikaRT-level value type (NOT op-layer machinery): one optional slot that carries a scalar (a bool, an integer or a double) OR a tensor. Every ctor is implicit on purpose. Pass a bare `bool`, `double`, an integer, a [`Tensor`](./ClikaRT/Tensor.md), or `std::nullopt` straight to a [`ScalarOrTensor`](./ClikaRT/ScalarOrTensor.md) parameter; spelling the wrap at a call site (`ops::ScalarOrTensor(x)`) is redundant noise. [`ops::ScalarOrTensor`](./ClikaRT/ops/ScalarOrTensor.md) remains a valid spelling via the alias below. | | [`Span`](./ClikaRT/Span.md) | A non-owning view over [`size()`](./ClikaRT/Span.md#size) contiguous elements of `T`, the C++17 stand-in for `std::span` (see the file note above). It never allocates, copies, or owns: the viewed memory must outlive every copy of the view. `T`'s constness is the access law: [`Span`](./ClikaRT/Span.md)`` reads, [`Span`](./ClikaRT/Span.md)`` writes through to the caller's memory. | | [`Stream`](./ClikaRT/Stream.md) | A handle to a device execution stream. Cheap to copy (it is an identifier, not the stream's resources). | | [`StreamOrDevice`](./ClikaRT/StreamOrDevice.md) | A value type: it holds a copyable [`Stream`](./ClikaRT/Stream.md) handle and/or a [`Device`](./ClikaRT/Device.md), so it crosses the ABI by layout; [`resolve_impl`](./ClikaRT/StreamOrDevice.md#resolve) is its one library entry (the placement law lives in the runtime). | | [`SynchronousScope`](./ClikaRT/SynchronousScope.md) | While alive, every op dispatched on the calling thread COMPLETES before the dispatch call returns, whichever stream runs it: the moment a call returns, its result is ready. Thread-local (it changes nothing for other threads and throttles no stream), so it opens anywhere, on a busy lane included; it trades away the throughput that asynchronous pipelining buys, for as long as it lives. Scopes nest. Non-copyable, non-movable. | | [`SynchronousStreamScope`](./ClikaRT/SynchronousStreamScope.md) | While alive, every op dispatched on the calling thread WAITS for completion before the dispatch call returns, and `stream` runs at most one task at a time, so the moment a dispatch returns, the result is ready ([`Stream::query_idle()`](./ClikaRT/Stream.md#query_idle) is true). Deterministic, ideal for debugging / per-op stepping; it trades away the throughput that async pipelining buys. The stream's prior limit is restored on destruction. Open it only on a quiescent stream (synchronize first). Non-copyable, non-movable. | | [`Tensor`](./ClikaRT/Tensor.md) | | | [`TracingScope`](./ClikaRT/TracingScope.md) | While alive, the calling thread builds a LAZY graph: ops return `Unscheduled` placeholder tensors carrying lineage, and NO kernel runs. Call [`Tensor::synchronize()`](./ClikaRT/Tensor.md#synchronize) to materialize the graph in one pass. Outside the scope execution is eager (the default). Non-copyable, non-movable. | ## Enumerations ### enum Status {#Status}
`enum class` **`Status`** `:` `std::int32_t`
Outcome of an operation. | Enumerator | Value | Description | | --- | --- | --- | | `Ok` | `0` | | | `InvalidArgument` | | | | `NotFound` | | | | `Unsupported` | | | | `Internal` | | | | `Unavailable` | | The work did not run: it was shed under load, ran past its deadline, or was canceled. Retry later (HTTP 503). |
Declared in `ClikaRT/common/result.h`, line 93
### enum DataType {#DataType}
`enum class` **`DataType`** `:` `std::int32_t`
The element format of a tensor's values. `int32`-backed for a stable ABI. The set covers booleans, signed/unsigned integers (including sub-byte widths), the IEEE-style floats, and the narrow floating formats used by quantized models (FP8 / FP6 / FP4). `Undefined` is the unset value. ABI note: the numeric values are part of the public ABI: new types append at the end; existing ones never reorder or drop. | Enumerator | Value | Description | | --- | --- | --- | | `Undefined` | `0` | | | `Bool` | | | | `Int2` | | | | `Int4` | | | | `Int8` | | | | `Int16` | | | | `Int32` | | | | `Int64` | | | | `UInt1` | | | | `UInt2` | | | | `UInt4` | | | | `UInt8` | | | | `UInt16` | | | | `UInt32` | | | | `UInt64` | | | | `Float16` | | | | `BFloat16` | | | | `Float32` | | | | `Float64` | | | | `Float8_E4M3` | | | | `Float8_E5M2` | | | | `Float8_E4M3FNUZ` | | | | `Float8_E5M2FNUZ` | | | | `Float8_E8M0` | | | | `Float6_E2M3` | | | | `Float6_E3M2` | | | | `Float4_E2M1` | | |
Declared in `ClikaRT/compute/data_type.h`, line 21
## Type aliases ### using OptionalTensor {#OptionalTensor}
`using` **`OptionalTensor`** `=` [`Tensor`](./ClikaRT/Tensor.md)
A tensor argument that may be omitted. It is just [`Tensor`](./ClikaRT/Tensor.md); pass a default [`Tensor`](./ClikaRT/Tensor.md)`{}` (an undefined tensor) to mean "not provided". The alias documents, at a signature, that the parameter is optional (e.g. a norm's `weight`/`bias`, an attention `mask`). Mirrors the role of `c10::optional<`[`Tensor`](./ClikaRT/Tensor.md)`>` in ATen, using the undefined-tensor sentinel [ClikaRT](./index.md) already carries.
Declared in `ClikaRT/compute/tensor.h`, line 950
## Functions ### is\_capability\_decline() {#is_capability_decline}
`bool` **`is_capability_decline`**(`std::string_view` `code_name`) `noexcept`
True when `code_name` (an [`Error::code_name()`](./ClikaRT/Error.md#code_name) or [`Result::code_name()`](./ClikaRT/Result.md#code_name)) names a capability decline: a case the runtime does not serve, whether the operation itself, the device, or the dtype, memory layout, quantization scheme, source and destination pair, geometry or parameter value it was asked for. It is the one failure a caller may serve another way (another device, another route); every other failure belongs to the operation, and so does a backend that runs nothing at all (`BACKEND_UNAVAILABLE`, `BACKEND_NOT_LOADED`, `BACKEND_DRIVER_ABSENT`). False for an empty or unknown name; names compare exactly, case included.
Declared in `ClikaRT/common/result.h`, line 160
### status\_of() {#status_of}
[`Status`](./index.md#Status) **`status_of`**(`std::string_view` `code_name`) `noexcept`
The coarse [`Status`](./index.md#Status) a failure named `code_name` carries: the `status()` the runtime reports beside that `code_name()`, so a binding or a log reader can class a failure from its name alone. [`Status::Internal`](./index.md#Status) for an empty or unknown name; names compare exactly, case included.
Declared in `ClikaRT/common/result.h`, line 166
### unwrap(T) {#unwrap}
`template <``typename T`, `typename std::enable_if>::value, int>::type` `=` `0``>`
`constexpr` `T&` **`unwrap`**(`T&` `value`) `noexcept`
The lvalue identity: the argument itself, by reference (no copy).
Declared in `ClikaRT/common/result.h`, line 495
### unwrap(T) {#unwrap-2}
`template <``typename T`, `typename std::enable_if>::value &&!std::is_lvalue_reference::value, int>::type` `=` `0``>`
`constexpr` `detail::unwrap_plain_t` **`unwrap`**(`T&&` `value`)
The rvalue identity: the argument's VALUE (one move), never a reference into it. A reference-returning arm would hand a range-for or an `auto&&` binding the storage of a temporary that dies at the end of the range-init full-expression; returning the value makes that binding own what it reads.
Declared in `ClikaRT/common/result.h`, line 507
### unwrap(Result\) {#unwrap-3}
`template <``typename T``>`
`T` **`unwrap`**([`Result`](./ClikaRT/Result.md)`&&` `r`)
The [`Result`](./ClikaRT/Result.md)`` read: move the value out, or raise on failure.
Declared in `ClikaRT/common/result.h`, line 513
### unwrap(Result\) {#unwrap-4}
`void` **`unwrap`**([`Result`](./ClikaRT/Result.md)`&&` `r`)
The [`Result`](./ClikaRT/Result.md)`` read: no value; run the failure check only.
Declared in `ClikaRT/common/result.h`, line 515
### GetVersionInfo() {#GetVersionInfo}
`std::string` **`GetVersionInfo`**()
Human-readable [ClikaRT](./index.md) version, e.g. "0.1.0".
Declared in `ClikaRT/common/version.h`, line 13
### quantized\_view() {#quantized_view}
[`QTensor`](./ClikaRT/QTensor.md) **`quantized_view`**([`Tensor`](./ClikaRT/Tensor.md) `tensor`)
Declared in `ClikaRT/compute/q_tensor.h`, line 92
### make\_quantized() {#make_quantized}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized`**(
    [`Tensor`](./ClikaRT/Tensor.md) `payload`,
    `std::string_view` `scheme`,
    [`Span`](./ClikaRT/Span.md)`` `logical_shape`,
    [`OptionalTensor`](./index.md#OptionalTensor) `global_scale` `=` `{}`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 114
### make\_quantized\_mxfp4() {#make_quantized_mxfp4}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized_mxfp4`**(
    [`Tensor`](./ClikaRT/Tensor.md) `blocks`,
    [`Tensor`](./ClikaRT/Tensor.md) `scales`,
    [`Span`](./ClikaRT/Span.md)`` `logical_shape`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 122
### make\_quantized\_mxfp8() {#make_quantized_mxfp8}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized_mxfp8`**(
    [`Tensor`](./ClikaRT/Tensor.md) `codes`,
    [`Tensor`](./ClikaRT/Tensor.md) `e8m0_scale`,
    [`Span`](./ClikaRT/Span.md)`` `logical_shape`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 148
### make\_quantized\_nvfp4() {#make_quantized_nvfp4}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized_nvfp4`**(
    [`Tensor`](./ClikaRT/Tensor.md) `codes`,
    [`Tensor`](./ClikaRT/Tensor.md) `sub_scales`,
    [`OptionalTensor`](./index.md#OptionalTensor) `global_scale`,
    [`Span`](./ClikaRT/Span.md)`` `logical_shape`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 166
### make\_quantized\_fp8() {#make_quantized_fp8}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized_fp8`**(
    [`Tensor`](./ClikaRT/Tensor.md) `codes`,
    [`Tensor`](./ClikaRT/Tensor.md) `scale`,
    [`Span`](./ClikaRT/Span.md)`` `logical_shape`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 195
### make\_quantized\_fp8\_blocked() {#make_quantized_fp8_blocked}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized_fp8_blocked`**(
    [`Tensor`](./ClikaRT/Tensor.md) `codes`,
    [`Tensor`](./ClikaRT/Tensor.md) `scale`,
    `std::int64_t` `block_size`,
    [`Span`](./ClikaRT/Span.md)`` `logical_shape`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 243
### make\_quantized\_affine() {#make_quantized_affine}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized_affine`**(
    [`Tensor`](./ClikaRT/Tensor.md) `codes`,
    [`Tensor`](./ClikaRT/Tensor.md) `scales`,
    [`Tensor`](./ClikaRT/Tensor.md) `biases`,
    `std::int64_t` `group_size`,
    `std::int64_t` `bits`,
    [`Span`](./ClikaRT/Span.md)`` `logical_shape`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 284
### make\_quantized\_gptq() {#make_quantized_gptq}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized_gptq`**(
    [`Tensor`](./ClikaRT/Tensor.md) `qweight`,
    [`Tensor`](./ClikaRT/Tensor.md) `qzeros`,
    [`Tensor`](./ClikaRT/Tensor.md) `scales`,
    [`OptionalTensor`](./index.md#OptionalTensor) `g_idx`,
    `std::int64_t` `bits`,
    `std::int64_t` `group_size`,
    [`quant::QuantizationConfig::ZerosConvention`](./ClikaRT/quant/QuantizationConfig.md#ZerosConvention) `zeros_convention`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 405
### make\_quantized\_bnb4() {#make_quantized_bnb4}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized_bnb4`**(
    [`Tensor`](./ClikaRT/Tensor.md) `packed`,
    [`Tensor`](./ClikaRT/Tensor.md) `absmax`,
    [`OptionalTensor`](./index.md#OptionalTensor) `nested_absmax`,
    [`OptionalTensor`](./index.md#OptionalTensor) `nested_quant_map`,
    [`OptionalTensor`](./index.md#OptionalTensor) `offset`,
    [`OptionalTensor`](./index.md#OptionalTensor) `quant_map`,
    `std::string_view` `quant_type`,
    `std::int64_t` `blocksize`,
    `std::int64_t` `nested_blocksize`,
    [`Span`](./ClikaRT/Span.md)`` `shape`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 421
### make\_quantized\_awq() {#make_quantized_awq}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized_awq`**(
    [`Tensor`](./ClikaRT/Tensor.md) `qweight`,
    [`Tensor`](./ClikaRT/Tensor.md) `qzeros`,
    [`Tensor`](./ClikaRT/Tensor.md) `scales`,
    `std::int64_t` `bits`,
    `std::int64_t` `group_size`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 431
### make\_quantized\_ct\_pack() {#make_quantized_ct_pack}
[`QTensor`](./ClikaRT/QTensor.md) **`make_quantized_ct_pack`**(
    [`Tensor`](./ClikaRT/Tensor.md) `packed`,
    [`Tensor`](./ClikaRT/Tensor.md) `scales`,
    `std::int64_t` `bits`,
    `std::int64_t` `group_size`
)
Declared in `ClikaRT/compute/q_tensor.h`, line 448
### operator+() {#operator-plus}
[`Tensor`](./ClikaRT/Tensor.md) **`operator+`**(`double` `scalar`, `const` [`Tensor`](./ClikaRT/Tensor.md)`&` `t`)
`scalar + t`, elementwise, the double-scalar mirror of `t + scalar`.
Declared in `ClikaRT/compute/tensor.h`, line 960
### operator\*() {#operator-mul}
[`Tensor`](./ClikaRT/Tensor.md) **`operator*`**(`double` `scalar`, `const` [`Tensor`](./ClikaRT/Tensor.md)`&` `t`)
`scalar * t`, elementwise.
Declared in `ClikaRT/compute/tensor.h`, line 962
### operator-() {#operator-minus}
[`Tensor`](./ClikaRT/Tensor.md) **`operator-`**(`double` `scalar`, `const` [`Tensor`](./ClikaRT/Tensor.md)`&` `t`)
`scalar - t`, elementwise: each element subtracted FROM the scalar.
Declared in `ClikaRT/compute/tensor.h`, line 964
### operator/() {#operator-div}
[`Tensor`](./ClikaRT/Tensor.md) **`operator/`**(`double` `scalar`, `const` [`Tensor`](./ClikaRT/Tensor.md)`&` `t`)
`scalar / t`, elementwise: the scalar divided BY each element.
Declared in `ClikaRT/compute/tensor.h`, line 966
### operator\<\<() {#operator-lshift}
`std::ostream&` **`operator<<`**(`std::ostream&` `os`, `const` [`Tensor`](./ClikaRT/Tensor.md)`&` `t`)
[Stream](./ClikaRT/Stream.md) a tensor's `to_string()` summary (shape, dtype, device, first values) to an `ostream`, so `std::cout << t << '\n'` works. Header-only; forwards to the (infallible) `to_string()`; reads values for any dtype, integers included.
Declared in `ClikaRT/compute/tensor.h`, line 971
## Platform notes {#platform_notes} ### macOS: JIT acceleration and the Hardened Runtime {#macos_jit} On macOS, [ClikaRT](./index.md)'s CPU runtime can accelerate some workloads by compiling specialized kernels at run time. The host application must be allowed to map executable memory: an application built with the Hardened Runtime needs the `com.apple.security.cs.allow-jit` entitlement. Without it, [ClikaRT](./index.md) detects the restriction at startup and serves its standard kernels; results are identical, and only the acceleration is unavailable. ## `ClikaRT/cli/cli.h` {#cli-h} ```cpp #include ``` Umbrella for the public command-line parser ([`ClikaRT::cli`](./ClikaRT/cli/index.md)): typed options / flags / positionals, subcommand routing, display + mutually-exclusive groups, auto help/usage, env-var fallbacks, and shell-completion generation. Every fallible call returns `Result`; the parser never throws, never exits, and never mutates argv. ## `ClikaRT/clika_rt.h` {#clika_rt-h} ```cpp #include ``` [ClikaRT](./index.md) public API umbrella header: one include for the whole public C++ API, the [`ClikaRT`](./index.md)`::` namespace with one sub-namespace per module, and the one link target `ClikaRT::ClikaRT` (`find_package(ClikaRT CONFIG)`). `AGENTS.md` beside these headers is the lookup index: what each module gives, which header to open for a task, and the gotchas. The modules, each under its own directory and namespace: `compute/` (`Tensor`, `Device`, `Stream`, the dtypes, the execution scopes, and `ops::`, the operator library), `nn/` (the module tree a model is built from, the packed leaves, the KV cache), `graph/` (`ModelGraph`, trace, compile, the queries and transforms), `io/` (checkpoints, media, the ONNX file), `runtime/` (the serving runtime: nodes, executors, pipelines), `tokenizer/`, `processor/`, `json/`, `template/`, `regex/`, `http/`, `cli/`, `progress/`, `profiler/`, `tables/`, `threading/`, `logging/`, `encoding/`, `platform/` and `common/` (the result type, `Span`, the environment names, the version). Three laws every program meets first. Every fallible call has two spellings: the distribution's default build returns values and raises [`ClikaRT::Error`](./ClikaRT/Error.md) on failure, a build with the `Result` surface returns `Result`; [`ClikaRT::unwrap`](./index.md#unwrap), [`CLIKART_TRY`](./index.md#CLIKART_TRY) and [`CLIKART_CHECK`](./index.md#CLIKART_CHECK) read the same under both, and a failure's `code_name()` is the name to branch on ([`common/result.h`](./index.md#result-h)). Operators are asynchronous: an `ops::` call queues its work and returns, and a host read (`to_string`, `item`, `item_as_vec`) waits for the value ([`compute/stream.h`](./ClikaRT/Stream.md), [`compute/scope.h`](./index.md#scope-h)). Every process that runs an operator or a model needs the license credential, `CLIKA_RT_LICENSE` or the per-user file, before its first call ([`common/env_vars.h`](./ClikaRT/env/index.md#env_vars-h)). ## `ClikaRT/common/macros.h` {#macros-h} ```cpp #include ``` ### Macros #### \#define CLIKART\_IS\_WINDOWS {#CLIKART_IS_WINDOWS}
`#define` **`CLIKART_IS_WINDOWS`** `0`
Declared in `ClikaRT/common/macros.h`, line 12
#### \#define CLIKART\_IS\_ANDROID {#CLIKART_IS_ANDROID}
`#define` **`CLIKART_IS_ANDROID`** `0`
Declared in `ClikaRT/common/macros.h`, line 18
#### \#define CLIKART\_IS\_LINUX {#CLIKART_IS_LINUX}
`#define` **`CLIKART_IS_LINUX`** `0`
Declared in `ClikaRT/common/macros.h`, line 24
#### \#define CLIKART\_IS\_MACOS {#CLIKART_IS_MACOS}
`#define` **`CLIKART_IS_MACOS`** `0`
Declared in `ClikaRT/common/macros.h`, line 40
#### \#define CLIKART\_IS\_IOS {#CLIKART_IS_IOS}
`#define` **`CLIKART_IS_IOS`** `0`
Declared in `ClikaRT/common/macros.h`, line 41
#### \#define CLIKART\_IS\_APPLE {#CLIKART_IS_APPLE}
`#define` **`CLIKART_IS_APPLE`** `(CLIKART_IS_MACOS || CLIKART_IS_IOS)`
Declared in `ClikaRT/common/macros.h`, line 44
#### \#define CLIKART\_IS\_X86\_64 {#CLIKART_IS_X86_64}
`#define` **`CLIKART_IS_X86_64`** `0`
Declared in `ClikaRT/common/macros.h`, line 49
#### \#define CLIKART\_IS\_ARM64 {#CLIKART_IS_ARM64}
`#define` **`CLIKART_IS_ARM64`** `0`
Declared in `ClikaRT/common/macros.h`, line 55
#### \#define CLIKART\_PUBLIC\_EXPORT {#CLIKART_PUBLIC_EXPORT}
`#define` **`CLIKART_PUBLIC_EXPORT`**
Declared in `ClikaRT/common/macros.h`, line 79
#### \#define CLIKART\_LOCAL {#CLIKART_LOCAL}
`#define` **`CLIKART_LOCAL`**
Declared in `ClikaRT/common/macros.h`, line 88
#### \#define CLIKART\_STATIC\_C\_API {#CLIKART_STATIC_C_API}
`#define` **`CLIKART_STATIC_C_API`**
Declared in `ClikaRT/common/macros.h`, line 97
#### \#define CLIKART\_HAS\_EXCEPTIONS {#CLIKART_HAS_EXCEPTIONS}
`#define` **`CLIKART_HAS_EXCEPTIONS`** `0`
Declared in `ClikaRT/common/macros.h`, line 112
## `ClikaRT/common/result.h` {#result-h} ```cpp #include ``` Value-returned result type for the [ClikaRT](./index.md) API. Holds a value on success or a Status + message on failure. Every fallible public method returns `Result` and never throws on its own. You turn a failure into an exception on the calling side with `value_or_throw()` (which raises [`ClikaRT::Error`](./ClikaRT/Error.md)), or inspect `ok()` / `status()` / `message()` and never pay for exceptions at all. Works with exceptions disabled: a consumer compiling with `-fno-exceptions` (or defining `CLIKART_NO_EXCEPTIONS`) gets a `value_or_throw()` that reports the failure to stderr and `std::abort()`s instead of throwing; the inspecting API (`ok()` / `status()` / `message()`) is unaffected. ── The error-handling vocabulary: each name's role ───────────────────── Two LAYERS live in this header and they are not duplicates: The LIBRARY's own boundary shims (not for consumer code): - [`CLIKART_RESULT(T)`](./index.md#CLIKART_RESULT) / [`CLIKART_UNWRAP(expr)`](./index.md#CLIKART_UNWRAP): how the public headers' inline wrappers adapt the library's `Result` to the built error-handling shape ([`CLIKART_USE_RESULT_TYPE`](./index.md#CLIKART_USE_RESULT_TYPE)). Consumer code never writes these. - [`CLIKART_INPLACE_RESULT(T)`](./index.md#CLIKART_INPLACE_RESULT) / [`CLIKART_INPLACE_UNWRAP(expr, self)`](./index.md#CLIKART_INPLACE_UNWRAP): the same adaptation for the IN-PLACE wrappers (the write-through ops and mutating tensor methods): under the value-returning surface they keep the historical `T&` return (the mutated `self`/`out`); under the `Result`-returning surface they return the impl's `Result` straight through. [`CLIKART_CHECK`](./index.md#CLIKART_CHECK) is the caller's mode-stable spelling for these calls. The caller vocabulary (each spelling compiles and behaves identically whichever shape the library was built with): - `ClikaRT::unwrap(x)`: read a value; extracts a `Result` (raising on failure) and forwards anything else unchanged, so the same call-site text serves both shapes. - Implicit extraction: `T x = fn(...);` / `g(fn(...))` compiles under BOTH shapes: a TEMPORARY `Result` converts to `T`, raising on failure exactly as `unwrap`. Call sites written against the value-returning surface keep compiling when a build opts into the `Result` surface, so a codebase adopts explicit handling gradually rather than all at once. Rvalue-only (a NAMED `Result` is read through `ok()`/`value()`/`unwrap`), and excluded for `bool` payloads (`operator bool` tests OKNESS everywhere, never the payload; read a bool payload through `unwrap`/`value()`). Note `auto x = fn(...);` still binds the `Result` itself; spell the type (or `unwrap`) to extract. - [`CLIKART_TRY(expr)`](./index.md#CLIKART_TRY): the CAPTURE idiom, "hand me data, never throw": yields a `Result` whatever happens, catching [`ClikaRT::Error`](./ClikaRT/Error.md) AND any other exception (nothing propagates). - [`CLIKART_TRY_OR_RETURN(var, expr)`](./index.md#CLIKART_TRY_OR_RETURN) / [`CLIKART_CHECK(expr)`](./index.md#CLIKART_CHECK): the PROPAGATE idiom for `Result`-returning consumer functions: on failure they RETURN the error (status + message + code\_name verbatim) to the enclosing function's caller; only [`ClikaRT::Error`](./ClikaRT/Error.md) is converted; foreign exceptions pass through untouched. ### Macros #### \#define CLIKART\_DETAIL\_HAS\_CXXABI {#CLIKART_DETAIL_HAS_CXXABI}
`#define` **`CLIKART_DETAIL_HAS_CXXABI`** `0`
Declared in `ClikaRT/common/result.h`, line 74
#### \#define CLIKART\_USE\_RESULT\_TYPE {#CLIKART_USE_RESULT_TYPE}
`#define` **`CLIKART_USE_RESULT_TYPE`** `0`
Declared in `ClikaRT/common/result.h`, line 87
#### \#define CLIKART\_TRY {#CLIKART_TRY}
`#define` **`CLIKART_TRY(...)`** `(::ClikaRT::detail::try_capture([&]() { return (__VA_ARGS__); }))`
CLIKART\_TRY: opt back INTO Result-style error handling. The public API returns values directly and raises [`ClikaRT::Error`](./ClikaRT/Error.md) on failure. When you would rather inspect a `Result` than catch, wrap the call: ```text Result r = CLIKART_TRY(ops::matmul(a, b)); if (!r.ok()) { log(r.message()); return; } use(r.value()); ``` Yields a `Result` where `T` is the (decayed) type the expression produces: `Result` for a `void` call, `Result` for a `Tensor`- or `Tensor&`-returning one. An expression that already produces a `Result` passes through as that same `Result` (never `Result>`), so the idiom reads identically whichever error-handling shape the library was built with. The expression is evaluated exactly once. A [`ClikaRT::Error`](./ClikaRT/Error.md) is captured with its status; any other exception is captured as `Status::Internal`; nothing propagates. This is the inverse of the internal unwrap-or-propagate idiom: it CATCHES exceptions at the call site and hands you data.
Declared in `ClikaRT/common/result.h`, line 581
#### \#define CLIKART\_RESULT {#CLIKART_RESULT}
`#define` **`CLIKART_RESULT(...)`** `__VA_ARGS__`
CLIKART\_RESULT / CLIKART\_UNWRAP: the two-mode public boundary shape. A fallible public method delegates to a `Result`-returning `*_impl` in the library and adapts that `Result` for the caller. These macros pick the adaptation at build time from [`CLIKART_USE_RESULT_TYPE`](./index.md#CLIKART_USE_RESULT_TYPE) (the [`CLIKART_USE_RESULT_TYPE`](./index.md#CLIKART_USE_RESULT_TYPE) CMake option, baked into `build_info.h`); the SAME header source compiles both ways, no per-method edit to flip. [`CLIKART_UNWRAP`](./index.md#CLIKART_UNWRAP) **supplies its own `return`**, so the wrapper body is just the unwrap; one macro serves both a value and a `void` boundary (a `void`-returning function may `return` a `void` expression): [CLIKART\_RESULT(Tensor)](./index.md#CLIKART_RESULT) to(Device d) const \{ [CLIKART\_UNWRAP(to\_impl(d))](./index.md#CLIKART_UNWRAP); \} [CLIKART\_RESULT(void)](./index.md#CLIKART_RESULT) write(...) const \{ [CLIKART\_UNWRAP(write\_impl(...))](./index.md#CLIKART_UNWRAP); \} - **CLIKART\_USE\_RESULT\_TYPE == 0** (default): the return type is the bare value `T` (`void`), and the unwrap is `return (expr).value_or_throw();`; the wrapper raises [`ClikaRT::Error`](./ClikaRT/Error.md) on failure, caller-side. Byte-behaviour-identical to the historical value-returning surface. - **CLIKART\_USE\_RESULT\_TYPE == 1**: the return type is `Result` (`Result`) and the unwrap is `return (expr);`; the impl's `Result` passes straight through; the wrapper never throws and the caller inspects `.ok()` / `.status()` / `.value()`. [`CLIKART_RESULT`](./index.md#CLIKART_RESULT) is variadic so a comma-bearing type ([`CLIKART_RESULT`](./index.md#CLIKART_RESULT)`(std::array)`, [`CLIKART_RESULT`](./index.md#CLIKART_RESULT)`(std::vector)`) is not split into two macro arguments. Boundaries that transform the impl's result before returning it (an in-place op returning `Tensor&` / `*this`, a templated readback, a contained callback) keep their explicit `value_or_throw()`; they are not `Result`-shaped and are the deliberate carve-outs (same family as the user-callback types).
Declared in `ClikaRT/common/result.h`, line 617
#### \#define CLIKART\_UNWRAP {#CLIKART_UNWRAP}
`#define` **`CLIKART_UNWRAP(expr)`** `return (expr).value_or_throw()`
Declared in `ClikaRT/common/result.h`, line 618
#### \#define CLIKART\_INPLACE\_RESULT {#CLIKART_INPLACE_RESULT}
`#define` **`CLIKART_INPLACE_RESULT(...)`** `__VA_ARGS__&`
CLIKART\_INPLACE\_RESULT / CLIKART\_INPLACE\_UNWRAP: the boundary shims for the IN-PLACE wrapper family (a write-through op returning its `out`, a mutating tensor method returning `*this`). The impl twins all return `Result`; the wrapper manufactures the reference: inline [CLIKART\_INPLACE\_RESULT(Tensor)](./index.md#CLIKART_INPLACE_RESULT) relu\_(Tensor\& self) \{ [CLIKART\_INPLACE\_UNWRAP(impl::relu\_(self), self)](./index.md#CLIKART_INPLACE_UNWRAP); \} - **CLIKART\_USE\_RESULT\_TYPE == 0** (default): the return type is `T&` and the unwrap is `(expr).value_or_throw(); return self;`, the historical reference-returning surface, raising [`ClikaRT::Error`](./ClikaRT/Error.md) caller-side on failure. - **CLIKART\_USE\_RESULT\_TYPE == 1**: the return type is `Result` and the unwrap is `return (expr);`; the impl's `Result` passes straight through (the caller already holds the buffer it handed in). The caller's mode-stable spelling for these calls is [`CLIKART_CHECK(...)`](./index.md#CLIKART_CHECK); reference-chaining is a value-surface-only idiom.
Declared in `ClikaRT/common/result.h`, line 643
#### \#define CLIKART\_INPLACE\_UNWRAP {#CLIKART_INPLACE_UNWRAP}
`#define` **`CLIKART_INPLACE_UNWRAP(expr, self)`** `(expr).value_or_throw(); return self`
Declared in `ClikaRT/common/result.h`, line 644
#### \#define CLIKART\_DETAIL\_CONCAT2 {#CLIKART_DETAIL_CONCAT2}
`#define` **`CLIKART_DETAIL_CONCAT2(a, b)`** `a##b`
Declared in `ClikaRT/common/result.h`, line 648
#### \#define CLIKART\_DETAIL\_CONCAT {#CLIKART_DETAIL_CONCAT}
`#define` **`CLIKART_DETAIL_CONCAT(a, b)`** `CLIKART_DETAIL_CONCAT2(a, b)`
Declared in `ClikaRT/common/result.h`, line 649
#### \#define CLIKART\_TRY\_OR\_RETURN {#CLIKART_TRY_OR_RETURN}
`#define` **`CLIKART_TRY_OR_RETURN(var, expr)`** `auto CLIKART_DETAIL_CONCAT(clikart_try_state_, __LINE__) = \ ::ClikaRT::detail::propagate_capture([&]() { return (expr); }); \ if (!CLIKART_DETAIL_CONCAT(clikart_try_state_, __LINE__).ok()) \ return {CLIKART_DETAIL_CONCAT(clikart_try_state_, __LINE__).status(), \ CLIKART_DETAIL_CONCAT(clikart_try_state_, __LINE__).message(), \ CLIKART_DETAIL_CONCAT(clikart_try_state_, __LINE__).code_name()}; \ var = std::move(CLIKART_DETAIL_CONCAT(clikart_try_state_, __LINE__).value())`
CLIKART\_TRY\_OR\_RETURN: the PROPAGATE idiom's value form, for `Result`-returning consumer functions. ```text Result mean_of(Tensor t) { CLIKART_TRY_OR_RETURN(auto m, ClikaRT::ops::mean(t)); return m.item(); } ``` Evaluates `expr` exactly once; on success declare-assigns (or assigns) `var` from the value; on a LIBRARY failure returns the error (status, message, and the fine `code_name` verbatim, through the three-argument `Result` constructor) to the enclosing function's caller. Only [`ClikaRT::Error`](./ClikaRT/Error.md) is converted; a foreign exception passes through untouched. The SAME text serves both error-handling shapes: under the value-returning surface `expr` yields the bare value (a failure throws and is converted here); under the `Result`-returning surface `expr` yields a `Result` that passes through unflattened. Error timing is the settle-time law (see `unwrap`): failures surface at the read site, and a settled failure re-reports identically on re-read. Expands to multiple statements; use it in statement context (never as an unbraced `if` body), one per source line. With exceptions disabled a failure already aborted inside the library, so a reached call only ever sees success.
Declared in `ClikaRT/common/result.h`, line 673
#### \#define CLIKART\_CHECK {#CLIKART_CHECK}
`#define` **`CLIKART_CHECK(expr)`** `do { \ auto clikart_check_state_ = \ ::ClikaRT::detail::propagate_capture([&]() { return (expr); }); \ if (!clikart_check_state_.ok()) \ return {clikart_check_state_.status(), \ clikart_check_state_.message(), \ clikart_check_state_.code_name()}; \ } while (false)`
CLIKART\_CHECK: the PROPAGATE idiom's effect form: `expr` is run for its effect (an in-place op, a write, a registration) and any LIBRARY failure returns the error (status/message/`code_name` verbatim) to the enclosing function's caller; only [`ClikaRT::Error`](./ClikaRT/Error.md) is converted, foreign exceptions pass through. The mode-stable spelling for the in-place `Tensor&`-returning ops ([`CLIKART_CHECK(ops::relu_(x))`](./index.md#CLIKART_CHECK)`;`) and for any `Result` call under the `Result`-returning surface. Single statement (safe as an `if` body); settle-time + sticky re-read semantics as on `unwrap`.
Declared in `ClikaRT/common/result.h`, line 691
## `ClikaRT/common/version.h` {#version-h} ```cpp #include ``` [ClikaRT](./index.md) version information. ## `ClikaRT/compute/scope.h` {#scope-h} ```cpp #include ``` RAII execution-mode scopes. [ClikaRT](./index.md) executes asynchronously by default; ops dispatch and return, and the work runs later. These scopes change that for the calling thread, for their lifetime: force every op to complete before dispatch returns (deterministic / debug), or switch to lazy graph-building (tracing). ## `ClikaRT/http/http.h` {#http-h} ```cpp #include ``` HTTP umbrella: the client ([`client.h`](./ClikaRT/http/DownloadOptions.md)) and the server ([`server.h`](./ClikaRT/http/index.md#server-h)) together. Include this to get both sides; include the role header directly ([`ClikaRT/http/client.h`](./ClikaRT/http/DownloadOptions.md) or [`ClikaRT/http/server.h`](./ClikaRT/http/index.md#server-h)) to name the side you use. ## `ClikaRT/nn/nn.h` {#nn-h} ```cpp #include ``` [ClikaRT](./index.md) public NN-module umbrella; include this one header for the whole `nn` surface. New public modules are added HERE (and only here); consumers and [`clika_rt.h`](./index.md#clika_rt-h) never enumerate the individual headers. A translation unit that defines a class deriving from `nn::Module` is compiled with run-time type information disabled, as the library is. ## `ClikaRT/profiler/profiler.h` {#profiler-h} ```cpp #include ``` Capture a profile of [ClikaRT](./index.md) compute work and export it: a Chrome trace you can open in `chrome://tracing` / Perfetto, a per-op summary, or the raw report JSON. While a capture is active, every op dispatched on the capturing thread (and on the streams it drives) is timed automatically; you do not instrument individual calls. Work that other threads dispatch is outside the capture: a serving pipeline runs its nodes on its own executor threads, so a capture opened around a pipeline request records only the capture's own markers. Profile a pipeline through the `clikart-cli` CLI's `bench --profile`, which captures where the nodes run; a model driven on the calling thread (a detector, a transcriber, an embedder) profiles through this session directly. The shape is RAII: ```text ClikaRT::ProfileSession session; { auto capture = session.start_capture("decode"); // ... run ops / drive streams ... } // capture ends here session.save("profile_out"); // chrome_trace.json + summary.txt + ... printf("%s\n", ClikaRT::unwrap(session.summary_text()).c_str()); const ClikaRT::ProfileSummary s = ClikaRT::unwrap(session.summary()); // the same numbers, typed printf("%zu allocations\n", s.total_allocations); ```