Tutorial - Stateful Stream Processing
=====================================

.. _tutorial-streamstateful:

WIP

SQs process streams. Sometimes, past results are relevant, e.g. a digital filter (such as a Kalman Filter or IIR Filter), such that our decisions will depend on the SQs history.

SQs can store state beteen invocations. Ordinary, each SQ has its own private execution namespace. A state variable (as a dictionary) is maintained within that namespace, and can be accessed by grabbing that variable, a dictionary called 'sq_state', from the namespace using 'global sq-state' at the start of the SQ's function. This tutorial shows how to use this, and the implications, as non-STREAMify'd SQs that use this will automatically enforce chronological execution on the stream.

**Things to mention**
* SQ has private state; this is never stored with other SQs
* Currently, any invocation can access and mutate this state. The same SQ should not have multiple iterations running simulataneously such that values can unexpectedly change during execution (we run to completion)
* By default, non STREAMify'd SQs with state will execute chronologically. Once they operate on a set of tokens that carry start_ticks of *t*, they will never operate on anything older than *t*. This can be restarted by providing a new trigger token with infinite time-interval width. This is performed by using control tokens and a SequentialRetrigger firing rule.