Module carry 

Carry-dependency analysis for per-point equation blocks.

Custom-wave per_point blocks run sequentially across the wave’s samples and the convention is that each iteration sees the previous iteration’s x/y/r/g/b/a as input (“trail across samples”). In practice many presets don’t actually depend on that carry — they write x = …; y = …; r = …; from the per-sample inputs (sample, value1, value2) and never read the previous values. In that case the samples are independent and the engine is free to evaluate them in parallel, which is a 4-8× win on dense waves.

This module walks the compiled Nodes once at preset-load time and classifies each per_point block as either safe-to-parallelize or carry-dependent. The check is conservative — a block is only marked safe if:

1. No carry-tracked variable (x, y, r, g, b, a) is read before being written in the block sequence (a read inside an equation that also writes the var is treated as carry-needing unless an earlier equation already wrote it).
2. No variable outside {x, y, r, g, b, a, sample, value1, value2} is written. Stray writes to qN / custom vars / per-frame vars leak state across samples.
3. No stateful / side-effecting function is called (rand, gmegabuf, megabuf, gmegabuf_set, megabuf_set, exec2, exec3, loop, while). These either carry per-eval state (gmegabuf is thread-local; samples on different workers would see split state) or are sample-order dependent (rand).

Enums

PerPointParallelism

Classification of a per_point block for the parallel-samples pass.

Constants

CARRY_VARS

Variables that thread state across iterations of eval_per_point (the caller seeds them from the previous sample’s output).

INPUT_VARS 🔒

Per-sample input variables the caller re-seeds every iteration — writes to these inside per_point are harmless because they get overwritten before the next sample runs.

UNSAFE_FUNCTIONS 🔒

Functions whose semantics depend on call order or thread-local state. A per_point block calling any of these cannot be safely sample-parallelised.

Functions

analyse_per_point

Analyse a compiled per_point block. Walks each equation’s operator tree once and tracks a running set of “already-written” identifiers to distinguish “first read = carry” from “first read after write = uses fresh value”.