Deterministic Automation

This page defines the design target for deterministic automation in DARTWIC. It is not a claim that Windows, a driver, a network, or arbitrary user code is hard real-time.

The key promise is narrower and testable:

After activation, DARTWIC-owned work on a prepared periodic path has a declared finite work set, uses pre-provisioned storage, does not wait behind configuration or unknown delivery code, and reports an explicit outcome when capacity or timing assumptions are exceeded.

That promise is why fixed RAPID channels and Native C++ DCode exist. They are not generic performance switches and fixed storage was not created merely because a signal has a known name.

Start here: choose the path that fits the automation

Dynamic channels and Lua are the normal choice for most DARTWIC automation. They are appropriate for operator workflows, sequencing, state machines, changing signal names, tables, imports, prompts, managed waits, and ordinary device integration. Do not choose fixed channels or Native C++ DCode merely because a task has a frequency.

Use the prepared fixed/native path when a control loop has known, repeatedly used numeric inputs and outputs, and measurement shows that it needs a tighter, more predictable DARTWIC-owned execution cost. That is often worth considering for a demanding 100–1,000 Hz acquisition → control → output loop, but the frequency is not the proof: a 100 Hz Lua task can be entirely appropriate, while a 1,000 Hz native task can still run late or overrun.

The engine must run near the control decision and hardware. A remote Interface does not make an engine loop local. Standard Linux is also not automatically a real-time operating system; a real-time OS or deliberately configured real-time-capable environment, such as a qualified Linux PREEMPT_RT deployment where appropriate, is part of a consequential tight-loop deployment. It still does not make unbounded callback or driver work safe.

For the full tradeoff table and deployment checklist, see Choose the simplest path that meets the measured need.

The three elemental requirements

These are independent. A task can start on time and still overrun. A group can preserve read -> control -> write ordering while the read fails. A completed write is not proof that a physical actuator moved.

1. Periodic execution

Periodic execution is not only a scheduler problem.

1. Periodic execution
   ├─ 1.1–1.3: release timekeeping
   │    absolute monotonic plan, no overlapping callback, explicit slip/miss
   └─ 1.4: predictable DARTWIC-owned work inside the released callback
        fixed inputs → explicit task logic → fixed output staging → fixed commit
                                         └→ bounded handoff

CAESAR handles the first branch: it advances from a monotonic release plan, does not overlap a callback with itself, and records skipped releases instead of replaying an unbounded backlog.

The second branch is the reason for the prepared fixed path. Calling a callback every 10 ms is not useful if the framework can turn one release into “look up arbitrary names, grow a container, allocate a publication, wait for configuration, or run an unknown telemetry callback.”

1.4 Predictable DARTWIC-owned work

This is a contract for DARTWIC-owned framework work. It deliberately does not ban a plugin’s device I/O, a user loop, or a user-selected timeout. Those remain permitted and are charged to the callback’s measured duration.

Why fixed RAPID channels exist

Fixed channels exist to remove recurring dynamic-memory and storage-management work from a repeated path. A normal dynamic-channel path is valuable for general-purpose use, but its storage and publication machinery may grow, move, allocate, or require name-based dispatch. Those are the wrong default assumptions for a control loop that has already declared its channel set.

The fixed design moves that work to configuration and activation:

Configuration / activation                         Every periodic release
--------------------------                         ----------------------
reserve fixed slots                         ─┐
name → {slot, generation} binding            │  copy declared input slots
resolve task's fixed handles                 ├─→ run task logic
reserve snapshots, output staging,           │  stage declared output slots
  publication records, and scratch buffers   │  atomically commit them
configure/seal the fixed layout              ─┘  hand off noncritical delivery

What each part buys

Fixed channels also give useful transaction semantics: declared inputs are the task’s coherent view for that release, and accepted outputs are staged before commit. That is important, but it is not their original determinism purpose. It does not make data fresh, coordinate separate devices, or order tasks. A TaskGroup provides local task order.

The precise boundary of the claim

“Fixed” alone does not prove an allocation-free or bounded release. A task meets the prepared-path memory claim only when all of its repeated resources have capacity already provisioned and the path has no fallback allocation.

For example, the ordinary RAPID transaction path currently preserves availability by allocating a FixedPublication when its prepared publication pool is busy. That is a reasonable general-purpose fallback, but it is explicitly not bounded timing. Likewise, a logically bounded queue is not a no-allocation guarantee if its backing container can still grow. A strict periodic profile must report resource exhaustion and follow a declared drop, coalesce, or defer policy instead of allocating on the task thread.

The strongest supported repeated-release path

The most predictable DARTWIC path is a CAESAR-scheduled task with declared RAPID fixed channels and prepared task resources. Use Native C++ DCode for supported repeated numeric logic, or a plugin that resolves fixed handles and reuses its own arrays/buffers during configuration. Keep inline dependencies native and bounded when they are part of the task’s cycle budget.

This is a positive engineering recommendation, not a ban on Lua or drivers. Lua, dynamic channels, arbitrary plugin work, and blocking calls remain valid where their flexibility is appropriate. They are simply outside the qualified prepared-core allocation result.

“Native” by itself is not enough: it does not bound a loop, sleep, driver call, native-library allocator, or transitive calculation chain. Likewise, “no inline Lua” is a useful condition for the strongest path but not a whole-system allocation proof. The allocation probe covers host C++ allocation/free in the measured engine path; it does not observe Lua allocation, direct malloc, or separately linked native/plugin DLL allocators.

Choose the simplest path that meets the measured need

Most DARTWIC automation does not need fixed channels or Native C++ DCode. Dynamic channels and Lua are the normal choice when flexibility, readable automation, changing channel sets, managed waits, tables, prompts, imports, or ordinary operator workflows matter more than a tightly controlled repeated execution cost.

Frequency alone is not the decision. A 100 Hz Lua task can be entirely appropriate; a 1,000 Hz native task can still miss its deadline if it blocks on a driver, waits on a lock, runs an unbounded calculation, or is scheduled late. Move to the prepared path because a measured control contract requires it, not because fixed channels are assumed to be universally better.

The engine process must run where the control decision is made. A remote Interface does not make a remote engine loop local to the hardware. Standard Linux is also not automatically a real-time operating system. For consequential tight-loop work, use a real-time operating system or a deliberately configured real-time-capable environment—such as a qualified Linux PREEMPT_RT deployment where appropriate—then measure scheduling latency, driver/transport latency, CPU contention, and device feedback on the actual target hardware. That host choice improves the deployment boundary; it does not excuse unbounded callback or driver behavior.

Why Native C++ DCode exists

Native C++ DCode is the companion to fixed channels on the prepared path:

DCode source
  → activation/build
  → generated C++ callback with prepared host bindings
  → periodic invocation

Its purpose is to remove Lua interpretation and dynamic script dispatch from the repeated automation callback. Static channel references can bind to the same fixed {slot, generation} handles during activation. The generated C++ still calls DARTWIC’s channel API; it does not replace RAPID’s storage or bypass validation, command authority, snapshots, or commit rules.

The required behavior is semantic, not aspirational:

A task configured for Native C++ either builds and activates its native callback, or activation fails. It must not silently fall back to Lua.

Native C++ does not make arbitrary code bounded. A native while loop, allocation, lock wait, sleep, or device operation is still callback work and appears in its duration/overrun health data.

Delivery and dependencies must not be surprises

A channel write can cause more work. The deterministic question is not “does that work exist?” but “where is it accounted for?”

prepared task writes a fixed output
        |
        +--> inline calculation / event
        |      runs before the writer returns
        |      ordered with this cycle and charged to its duration
        |
        +--> UI / history / Share / recording / ordinary observer
               receives bounded asynchronous handoff
               not an acknowledgement and not part of control order

An inline Lua calculation is allowed, but it is not free because the initiating task is Native C++. If the calculation is reached synchronously, its interpreter time and any wait on its execution mutex are part of the writer’s cycle budget. Make it bounded, move it to an explicitly asynchronous design, or treat the resulting overrun as an application fault.

Telemetry, history, Share, and UI delivery have the opposite rule: they must never run arbitrary consumer work on the CAESAR callback. A bounded handoff may drop or coalesce an asynchronous notification under pressure while the accepted live channel value remains committed. The loss/lag counter is part of the health evidence; control code must not wait for a subscriber as acknowledgement.

2. Health and response

Health is intentionally separate from scheduling. The task that is blocked cannot be responsible for reporting its own hang.

CAESAR reports release lateness, skipped releases, callback failure, completion duration/overrun, and an active-overdue callback. A health observer must itself remain small and nonblocking. DARTWIC reports the condition; the application chooses whether to inhibit a command, hold state, alert an operator, or apply a hardware-specific safe response.

For a prepared task, health should also make the framework assumptions visible: configuration rejection, fixed-handle failure, publication/queue exhaustion, asynchronous-delivery loss, and the identities/durations of inline dependencies.

3. Deterministic composition

Task input/output snapshots do not establish a control cycle. They do not prove the producer ran this cycle, succeeded, or published fresh data. Task order does.

task_group device_cycle:
    run: device_read
    run: control
    run: device_write

When these members are due together, the group executes device_read, waits for it to return and commit accepted writes, then executes control, then device_write. Members do not overlap inside that group. member_last_outcomes records completed, callback_failed, skipped_stopped, not_dispatched, or not_yet_released.

The group preserves ordering; it does not invent success or freshness. If device_read fails, control can still see the prior committed measurement unless the application checks validity/freshness and makes a different decision. That policy belongs to the automation and device safety design.

Build and qualify a prepared automation

1. Declare the release contract. Frequency, allowable start lateness, completion deadline, and missed-release policy.
2. Declare the fixed contract. Every input/output, fixed capacity, fixed binding, publication/queue capacity, and inline dependency.
3. Prepare before release. Configure modules and channels, resolve fixed batches, reserve buffers and packet layouts, establish connections where possible, build Native C++ DCode, then activate.
4. Keep configuration out of the cycle. Rebind/reconfigure in a lifecycle or maintenance phase; treat a rejected prepared release as an explicit result.
5. Keep external delivery out of the cycle. Never make telemetry, history, UI, Share, logging, or a subscriber acknowledgement a synchronous control step.
6. Measure the entire declared path. Release lateness, callback duration, missed releases, inline dependency time, pool/queue exhaustion, TaskGroup outcomes, transport duration, connection state, and device feedback.
7. Exercise failure deliberately. Test allocator pressure, publication exhaustion, telemetry pressure, a slow inline calculation, configuration contention, disconnected hardware, late wakeups, and failed/stale acquisition.

The useful outcome is not a generic “deterministic” label. It is a documented statement such as:

At 100 Hz, control_task uses 6 declared fixed inputs and 2 fixed outputs.
Its Native C++ callback and fixed publication resources are prepared at activation.
It has no synchronous telemetry delivery and declares one inline calculation.
Late release, callback overrun, stale input, failed read, and resource exhaustion
each produce a recorded condition and a defined application response.

That is the design DARTWIC is built to make possible: predictable framework work, explicit user work, observed failures, and a deliberate response.

References

CAESAR Tasks, Channels, and Execution and Timing describe the scheduler and channel APIs. F Prime’s rate-group guidance and health component illustrate the same architectural separation between periodic dispatch, ordered synchronous work, and independent health supervision.