Nodes outputs of which depend solely on their inputs in at any point of time are cool. They easy to understand, test, and compose. But building a useful device using only such pure nodes is not realistic. Someone needs to keep state along program run time.
A node can define state data that will persist for the time the program
executes. In other words, a node can put some value to the state in evaluate
call and retrieve that value in any of subsequent evaluate
invocations.
Let’s make a simple count
node that will increment a value by one each time a
pulse is sent to it. Also, we’ll make the step size configurable and provide a
pulse input to reset the counter to zero.
xod/core/count
node with similar functionality. But let’s forget about it for a moment.
As always, when you make a C++ node, start with a
new patch, add required terminals, and the not-implemented-in-xod
node.
It’s a good idea to provide a resonable default value for STEP
. We’ll set it
to 1.
Double-click on not-implemented-in-xod
node to open the code editor.
You define the persistent state using the State
struct in C++. In our case,
we need to store a single counter value, so our struct will have a single field.
Let’s call it counterValue
:
struct State {
Number counterValue = 0;
};
All state values, regardless of type, start with their default values. The
default value for numbers is 0
anyway, so this initialization of
counterValue
through assignment is not required. Although the definition of
the field is necessary, of course. We set it to 0
here just to demonstrate a
possibility to initialize with another value like 42
.
Now you can use getState(Context ctx)
function to access the persistent state
instance associated with the context node. The outline is:
// ...
void evaluate(Context ctx) {
State* state = getState(ctx);
// Read
Number x = state->counterValue;
// Do some magic with `myCounter`
// Write
state->counterValue = x;
}
The state
is just a plain pointer to the State
instance. Of course, you may
use its fields directly without any intermediate variables.
As you know from Data types article pulses have no values. To
check whether a pulse on the pin was fired in the current transaction we should
use isInputDirty
function, not
getValue
. It doesn’t read values, instead it returns true
if an upstream
node just emitted a new value for the pin specified.
Finally, here is an example implementation of our counter:
struct State {
Number counterValue;
};
{{ GENERATED_CODE }}
void evaluate(Context ctx) {
State* state = getState(ctx);
if (isInputDirty<input_INC>(ctx)) {
// Update the state
Number step = getValue<input_STEP>(ctx);
state->counterValue += step;
} else if (isInputDirty<input_RST>(ctx)) {
// Reset the state
state->counterValue = 0;
} else {
// The evaluation caused by `STEP` update. Do nothing, return early to
// avoid emission of a duplicate value.
return;
}
// Emit the updated value accessing the field directly.
emitValue<output_OUT>(ctx, state->counterValue);
}
The State
struct is not the only thing which keeps data across transactions.
Any node owns its output value as well. And the
getValue
function is allowed to
access the most recent values set on outputs.
In our case, the OUT
value always matches the value we store in State
. So
it’s a duplication we can get rid off to save few bytes of RAM and make the code
more compact:
// The internal state is no longer required
struct State { };
{{ GENERATED_CODE }}
void evaluate(Context ctx) {
if (isInputDirty<input_RST>(ctx)) {
// On reset unconditonally emit 0
emitValue<output_OUT>(ctx, 0);
} else if (isInputDirty<input_INC>(ctx)) {
Number step = getValue<input_STEP>(ctx);
// Read the most recent value...
Number counterValue = getValue<output_OUT>(ctx);
// ...and immediately emit a new one
emitValue<output_OUT>(ctx, counterValue + step);
}
}
Note how we changed the order of pulse checks to preserve the priority of RST
pulse over the INC
pulse.
Well done! The node is ready. Use a couple of buttons and a watch
node to test
and play with it.
Using persistent state is easy. Remember though, data stored in it consumes RAM. Also, stateful nodes in many cases are more complicated than their pure counterparts; it’s easier to seed a bug in it. Use them with care.
When possible, split a big stateful node into two smaller nodes: a stateful thin node and pure fat node. In other words, try to keep the most functionality in stateless nodes.