---
title: C++ Node API Reference
---

# C++ Node API Reference

## Basic types

#### `Number`

Represents a XOD number. In current implementations typedef’ed to IEEE 754
32-bit floating point data type.

#### `TimeMs`

Represents a big integer to store time values expressed in milliseconds.
Typedef’ed to 32-bit unsigned integer.

#### `XString`

Represents XOD string. Typedef’ed to [`List<char>`](#List), so the same methods
and functions may be used to manipulate it.

#### `Context`

An opaque type to distinguish a particular instance of node among other nodes
of the same type.

Required as an argument for most node functions. Can be thought as an explicit
`this` in many OOP languages, or like the `self` in Python.

#### `State`

A user-defined struct to store node’s data for a lifetime of the program. Each
node type has its own `State` definition.

<a name="input_xxx"></a>
#### `input_$$$`

Automatically generated descriptor for each of node’s inputs. Never
instantiated. Used as a template argument in functions to access input data.

`$$$` gets replaced by a pin label as is. For example, `input_FOO`, `input_Smin`.
If a node has a single unlabeled input, `input_IN` is generated for it. If a
node has multiple unlabeled inputs, they are referred as `input_IN1`, `input_IN2`,…,
`input_IN7`.

<a name="output_xxx"></a>
#### `output_$$$`

Automatically generated descriptor for each of node’s outputs. Never
instantiated. Used as a template argument in functions to access output data.

`$$$` gets replaced by a pin label as is. For example, `output_BAR`, `output_Tc`.
If a node has a single unlabeled output, `output_OUT` is generated for it. If a
node has multiple unlabeled outputs, they are referred as `output_OUT1`,
`output_OUT2`,…, `output_OUT7`.

XOD runtime supports no more than seven outputs on C\++ nodes.

## Node functions

<a name="evaluate"></a>
#### `void evaluate(Context ctx)`

Entry-point function for any C\++ node. Called by the runtime when a node
requires re-evaluation for whatever reason: input data update, schedule
timeout, etc. Each C\++ node must implement `evaluate`.

<a name="getValue"></a>
#### `ValueT getValue<input_$$$|output_$$$>(Context ctx)`

Returns the most recent value on an input or output pin. The result type
`ValueT` depends on pin data type and could be `bool`, `Number`, etc.

Note, the pulse type has no values. It’s meaningless to call `getValue`
on a pulse-type pin. To know if a pulse was fired use
[`isInputDirty`](#isInputDirty) instead.

A node owns its output values, so in simple cases, they could serve both
as values for downstream nodes *and* as node’s state storage. In such cases
use `getValue<output_$$$>(ctx)` to access the last emitted output value.

<a name="emitValue"></a>
#### `void emitValue<output_$$$>(Context ctx, ValueT value)`

Sets new value on an output pin. The argument type `ValueT` depends on pin data
type and can be `bool`, `Number`, etc.

A call to `emitValue` causes immediate downstream nodes to be re-evaluated
within the current transaction even if the output value has not changed. If
it’s cheap to check, avoid sending duplicate values.

To emit a pulse, use `true` as the `value`.

<a name="isInputDirty"></a>
#### `bool isInputDirty<input_$$$>(Context ctx)`

Returns `true` if and only if the input pin specified has got a newly emitted
value during the current transaction.

<a name="getState"></a>
#### `State* getState(Context ctx)`

Returns a pointer to the persistent state storage for the current node. The
[`State`](#State) structure is defined by the node author. Fields could be
updated directly, with the pointer returned, no commit is required after
a change.

<a name="transactionTime"></a>
#### `TimeMs transactionTime()`

Returns time of the current transaction since the program started, in
milliseconds. Stays constant for the whole duration of any particular
transaction. Prefer this function to `millis` to avoid time difference error
accumulation.

<a name="setTimeout"></a>
#### `void setTimeout(Context ctx, TimeMs timeout)`

Schedules a forced re-evaluation of a node past `timeout` milliseconds after the
current transaction time.

A node may have at most one scheduled update. If called multiple times, the
subsequent calls cancel the previous schedule for the node.

Pass `0` for `timeout` to schedule evaluation right after the current transaction
completes. Effectively it forces a new transaction trigger after the current.

<a name="clearTimeout"></a>
#### `void clearTimeout(Context ctx)`

Cancels scheduled evaluation of a node (if present). Safe to call even if the
update was not scheduled.

<a name="isTimedOut"></a>
#### `bool isTimedOut(Context ctx)`

Returns `true` if node’s schedule timed out right at the current transaction.
Unless scheduled again will return `false` since the next transaction.

## List objects

Lists in XOD are not classical linked lists,
nor vectors. They are smart (or dumb) *views* over existing data. The only
useful thing a list can do is to create an `Iterator<T>` allowing to enumerate
list values from the head to the tail.

**Usage example**

```cpp
Number sum(List<Number> numbers) {
    Number result = 0;
    for (Iterator<Number> it = numbers.iterate(); it; ++it)
        result += *it;
    return result;
}
```

<a name="List"></a>
#### `List<T>`

A list of elements of type `T`.

A `List<T>` is a thin
[Pimpl](https://en.wikipedia.org/wiki/Opaque_pointer)-wrapper around a
`ListView<T>`. Since internally a `List<T>` contains just a single pointer
passing a list by value is a cheap operation.

#### `List<T>::List()`

Constructs a new nil (null element) list.

#### `List<T>::List(const ListView<T>* view)`

Wraps a `view` into a list. The `view` must be kept alive for the whole list
lifetime. Otherwise, the program will crash. This requirement is *not* checked
automatically.

<a name="List--iterate"></a>
#### `Iterator<T> List<T>::iterate() const`

Creates a new iterator pointing to the first element of the list.

<a name="Iterator"></a>
#### `Iterator<T>`

An iterator of `List<T>`. Iterators are expected to be short-living objects to
enumerate elements of a list. They should not be cloned or passed around. An
iterator points either to a valid element or it points out of list bounds. The
later is used to denote iteration completed.

<a name="Iterator--bool"></a>
#### `Iterator<T>::operator bool() const`

Implicit cast to `bool` type. Returns `true` if the iterator points to a valid
element, i.e. if the iterator is valid.

<a name="Iterator--deref"></a>
#### `T Iterator<T>::operator*() const`

Returns the element pointed by the iterator. Mimics pointer dereference.
Returns a default value for type `T` if the iterator is not valid.

<a name="Iterator--value"></a>
#### `bool Iterator<T>::value(T* out) const`

Checks validity and retrieves element at once. Returns `true` if the iterator is
valid, writes the element into `out` in that case. If the iterator is invalid
returns `false` and keeps `out` intact.

<a name="Iterator--increment"></a>
#### `Iterator& Iterator<T>::operator++()`

Advances the iterator to the next element. May make it invalid. Conventionally
returns self.

## List functions

<a name="length"></a>
#### `size_t length(List<T> xs)`

Returns a length of the list. To compute it iterates over all elements, so it’s
not a trivial operation, so prefer caching the result over calling `length`
multiple times.

<a name="dump"></a>
#### `size_t dump(List<T> xs, T* outBuff)`

Copies elements from list `xs` into the flat `outBuff`. A caller must guarantee
that the buffer pointed has enough size to contain all elements of the list.
Otherwise, the program will crash.

<a name="foldl"></a>
#### `TR foldl(List<T> xs, TR (*func)(TR, T), TR acc)`

Performs [left fold](https://en.wikipedia.org/wiki/Fold_(higher-order_function))
(also known as “reduce”) of the list `xs` using `func` reducer function and
`acc` as starting value for the accumulator.

<style>
/* Shift the content to assist better visual structure perception */
.ui.text.container p,
.ui.text.container pre {
  margin-left: 4ex;
}
</style>