CogniTabScript documentation
/

Runtime v2.81 · Updated Sep 30, 2026

Flow

Read-only Class

Static controls for starting named macro flows in parallel.

Syntax

Flow

This class cannot be constructed directly.

Parameters

None

Returns

—

Behavior / side effects

Static controls for starting named macro flows in parallel. At most two background flows can run beside the main flow, and only one live invocation of a given named flow is allowed, including while it is paused or stopping. Flow.start() returns immediately after the coordinator accepts the branch; background flows may start peer flows. Variables are isolated per branch and never merge into the caller. The main flow waits for all background flows before Run completes. An invalid or duplicate name, a full background-flow limit, any branch error, System.stop(), or Main Stop ends the whole macro. Each numbered background dock control can temporarily Pause or Resume only that branch; it has no per-branch Stop. Main Pause or Resume applies to every branch, and global Resume also clears branch-local pause flags. Touch gestures from different branches can cancel each other. ScreenCapture and audio capture policies are shared globally. Storage shares the same persistent keys across branches and is not an inter-process messaging channel.

Execution

  • Blocking: Conditional
  • Thread safety: Use separate objects per flow
  • Parallel execution: Yes

Flow.start creates an isolated background executor and returns an Int ordinal, not a handle. At most two background flows run with the main flow. The main flow waits for background completion; any flow error or System.stop() stops the entire Run.

Example

# Start a configured worker while the main flow keeps running
worker_no = Flow.start("watch_enemy", {"labels": ["boss", "guard"]})
MacroPanel.notify("Background flow #" + str(worker_no) + " started")

Errors / limitations

No additional limitations documented; follow the parameter and behavior contract above.

Related APIs

Fields

NameDescription
paramsdict
Read-only copied input for the current branch. The main flow receives an empty dict. Each read returns safe data detached from coordinator and parent-VM collections.

Methods

1 method

Flow.start

Static Method

Start one configured named flow without blocking the caller.

Syntax

Flow.start(name, params=None)

Parameters

NameDescription
nameString
Exact configured flow name resolved by the macro coordinator.
Required · Positional or named
No default
paramsdict?
Optional safe copied input exposed as Flow.params in the started branch.
Optional · Positional or named
Default: None

Returns

Int — A positive, monotonically increasing branch instance number for dock status and logs; it is not a control handle.

Behavior / side effects

Start one configured named flow without blocking the caller. The name is matched by the macro coordinator. Params are copied before dispatch and may contain only None, Boolean, finite numbers, String, list, tuple, and dict with String keys, within runtime depth and size limits; callables, domain/resource values, and cyclic collections are rejected.

Execution

  • Blocking: No
  • Thread safety: Use separate objects per flow
  • Parallel execution: Yes

Returns after the coordinator accepts a named flow; it does not join that flow. Inputs are copied before dispatch.

Example

# Start recognition and telemetry beside the main flow
recognition_no = Flow.start("recognition", {"region": "arena", "threshold": 0.86})
telemetry_no = Flow.start("telemetry")

# Inside the configured recognition flow, read this branch's copied input
region_name = Flow.params.get("region", "full_screen")
threshold = Flow.params.get("threshold", 0.8)

Errors / limitations

No additional limitations documented; follow the parameter and behavior contract above.

Related APIs