Addressing FSM-ambiguity in wires

Issues with wire state

Wires are driven as a Finite State Machine (FSM). This is a one-dimensional value; internally a integer from 0 to 4.

type Wire<T> = {
  // ...
  /** FSM state: RESET|RUNNING|IDLE|PAUSED|STALE */
  state: WireFSM;
  // ...
};

type WireFSM =
  | FSM_RESET
  | FSM_RUNNING
  | FSM_WIRED_IDLE
  | FSM_WIRED_PAUSED
  | FSM_WIRED_STALE;

Where state is used today

The 0-4 states are used here:

In wire (aka createWire) during creation:
- Sets RESET
In wire during a run:
- Throws if RUNNING is already set (infinite loop check)
- If PAUSED
- Sets IDLE OR RESET depending if there were subscribers (sigRS)
- Repeats this for all wire.inner children
- Else
- Sets RESET as part of wireReset
- Sets RUNNING for wire.fn() call duration
- Sets IDLE OR RESET depending if there were subscribers (sigRS)
In _runWires before calling wires:
- Moving from PAUSED -> STALE if needed _(i.e STALE means PAUSED_ANDSTALE)
- Calling a wire if it's NOT PAUSED AND NOT STALE _(i.e PAUSED_ANDSTALE)
In wirePause:
- Sets PAUSED for this wire and all inner wires

This already has problems, seen right in the FSM names themselves: I'm overloading terms to imply, for instance, that a wire can never be idle and stale, and that a stale wire is a paused wire. This gets really messy with the introduction of computed-signals that also have a stale state (which is stale but never paused; oh no) and needs to be skipped somehow possibly via another state.

In signal (aka signalBase) during a read-subscribe:
- If this is computed-signal whose wire is STALE or NOT_WIRED, run it
In signal during any read (pass or subscribe):
- If this is computed-signal whose wire is STALE or NOT_WIRED, run it
In signal when writing a wire:
- If this is computed-signal already
- Set saved wire as RESET
- Set incoming wire as STALE (so _runWires doesn't call it)
In _runWires:
- First loop: If wire belongs to a computed-signal set to STALE
- Second loop: If wire is PAUSED or STALE skip it

Issues with this state model

Note that I'm not interested in trying to prevent people from explicitly doing bad things like wire.state = xyz. I just don't want to introduce unexpected or accidental state transitions.

Here are some of those pitfalls:

If you call wirePause during the wire function run (wire.fn) you can move your own state from RUNNING into PAUSED skipping infinite loop detection (!).
Calling a wire to unpause is magic. Especially since it breaks the principal "Wires can always be run manually by calling them and this won't cause other side-effects within the engine."
Calling a wire of a computed-signal removes its STALE state but doesn't update the stored value of the computed-signal This breaks the signal until the wire is marked STALE again.
Computed-signal can be initialized with any wire including ones that are PAUSED or that have already had their function wrapped to support DOM patching. When the computed-signal is taken down (writing a value so it becomes a normal signal) the wire is set to RESET. This breaks the wire and prevents it from doing any other tasks such as DOM patching since all subscriptions have been removed. There's no way to know it had other tasks; they're lost in the wrapping.
Although computed-signals are set as STALE in _runWires, it's possible that they'll run somehow and end up as IDLE between the 1st and 2nd run loops. This means _runWires must check wire.cs and not rely only on state... Is belonging to a computed-signal a state now?
It doesn't make sense to pause a computed-signal but it's not good enough to just hope they don't try pausing it; it can happen accidentally. This happens in wire function wrapping (used to patch a single wire into multiple areas of the DOM; i.e chaining). If one of those chains was in a when() block, the wire would be re-adopted and when() would pause all patches, not only its child elements.

Issues with chaining

The issue above about chaining is very concerning. It also came up when I tried fixing computed-signal's to have their saved value updated when a wire is manually run - a small optimization but worth considering.

Why not just wrap the wire function like DOM patching does? The value will be updated via closure...

It'd be impossible to undo. Computed-signals need to be taken down, and there's no way to unwrap a function. It's also not safe to restore to the previously seen function since the wire could have been wrapped again during the computed-signal's lifetime.

Fixes

This is how I'm trying to address all these issues...

Both pause and resume should be dedicated methods

Wires should always run when manually called since it's their expected behaviour. Don't have a magic "unpausing" call. This means a new wireResume next to wirePause.

It'll drop bundle size.

Replace chaining with a `Set` of post-run calls

It's not clear, explicit, and debuggable to have a dedicated wire.hooks Set that tracks all the post-run actions. During takedown of a computed-signals I can use wire.hooks.delete(...) via function reference.

Might add bundle size.

Split state into a bitmask

I've seen projects like Kairo do that. It could be smaller than adding more individual properties like wire.paused.

It'll add to bundle size.

Here's how I broke it down:

[IS_CW][IS_WIRED][IS_RUNNING][IS_PAUSED][IS_STALE]

I can drop IS_CW and use wire.cs instead. This is a two-way link between a signal and wire. It's there for principles of consistency and debugging, so I'm keeping it. I can drop IS_WIRED and use wire.sigRS as well.

[IS_RUNNING][IS_PAUSED][IS_STALE]

I'm still overloading the term "stale" which mostly means "skip" in _runWires context and "run later" in other contexts.

[IS_RUNNING][SKIP_ME][WAS_SKIPPED]

Lastly I need to convey that a skipped wire is overdue for a run. I'd also like wireReset to be able to indicate that it's uninitialized; wire.run doesn't work since wires can always be manually reset even after they're run.

[RUNNING][SKIP_RUN_QUEUE][NEEDS_RUN]

Here's how this works for the above cases:

Pause/Resume:

wirePause: Sets SKIP_RUN_QUEUE. Has no impact to computed-signals because they already have SKIP_RUN_QUEUE.
_runWires: If SKIP_RUN_QUEUE is set then set NEEDS_RUN. This is the same for computed-signals too.
wireResume: Clears SKIP_RUN_QUEUE only if it's NOT a computed-signal.

Computed-signals:

signal setup: Sets SKIP_RUN_QUEUE, wire.cs, and wire.hooks.add(...).
signal read-subscribe: If NEEDS_RUN, run.
signal any read (pass or subscribe): If NEEDS_RUN, run.
_runWires: If SKIP_RUN_QUEUE is set then set NEEDS_RUN. This is the same for paused wires too.
signal takedown: Uses wireReset (clears state; sets only NEEDS_RUN). Uses delete wire.cs and wire.hooks.delete(...).

Reset via wireReset:

Clears all state and sets only NEEDS_RUN. Because it's not idling yet? This helps computed-signals know to auto-run the wire on read to initialize the wire's sigRS and propagate subscriptions (i.e sigIC).
TODO: Benchmark:
- if (wire.sigIC.size) wire.sigIC = new Set() vs
- wire.sigIC = new Set() vs
- wire.sigIC.clear()

Scenarios that are fixed using this model:

Mark a wire as paused (sets SKIP_RUN_QUEUE), have a signal try to run it (sets NEEDS_RUN), and then manually run it - it'll clear NEEDS_RUN but leaves it as SKIP_RUN_QUEUE so it's still paused.
Resume a wire during it's wire run - it doesn't break the RUNNING state.
Manually run a computed-signal's wire that is in NEEDS_RUN - it'll clear NEEDS_RUN and update the signal's saved value using wire.hooks.
Create a computed-signal using an existing/used wire - it sets SKIP_RUN_QUEUE (has no effect on pausing/resuming since they respect wire.cs). If the wire has never run it'll be in NEEDS_RUN and I'll run it; else it'll be idle* and nothing happens. It's always safe to use sigRS.

Other considerations:

I don't warn or throw if the wire they pass has an empty sigRS. If they pass an unrunnable wire with no subscriptions it should be easy to debug outside of a computed-signal. Not my problem.
Regarding the *; it has to be idling (RUNNING=0) since if it was (RUNNING && NEEDS_RUN) they'd be initializing the computed-signal within the running wire and it'll throw a loop error.

nettybun / haptic