APIC – State Architecture & Guide

IEngineSync – Frame Synchronization Interface

The EngineSync abstraction provides deterministic frame synchronization between the engine execution loop and an external synchronization source. Synchronization is driven through a callback (syncSignalFn) which typically queries a stream connected to external hardware (for example, a discrete sync line, FPGA pulse, or external timing source).

The synchronization layer ensures that engine frame progression is aligned with an external hardware timing reference rather than relying solely on internal software timing.

How most projects use this: in a typical CoreEngine project, EngineSync is configured declaratively in the project's config file rather than called directly from your own model/app code, for example:

"EngineSync": {
  "stream": "SocketTCPTLMStream",
  "element": "LRU_KZ.TLMAiding.SystemEventNumber",
  "syncPerMS": "1000",
  "scale": { "engType": "float", "scale": 1000 },
  "affinity": "0,1,3,4-6",
  "priority": 6
}

The engine reads this configuration and creates, starts, and stops the synchronization instance internally. The IEngineSync / CEngineSyncBase C++ API documented below is what the engine uses internally to implement this behavior - it is framework-internal machinery, not something most CoreEngine model/app developers call directly.

Public API – IEngineSync

Method	Description
`static CEngineSyncBase* Create(...)`	Factory method that constructs a concrete synchronization engine. Parameters: `streamName` – Logical stream used to monitor the external sync source. `elementName` – Specific element within the stream that carries the sync signal. `affinity` – CPU affinity mask controlling which cores the sync thread may execute on. `syncSignalFn` – Callback function used to evaluate the synchronization condition (e.g., edge detection, level check). Returns a configured synchronization instance ready for `Start()`.
`Start()`	Activates the synchronization mechanism. Typically spawns or enables a real-time wait loop that blocks frame progression until the synchronization condition is satisfied.
`Stop()`	Stops synchronization and releases any associated execution resources. Ensures the engine no longer waits on the external sync condition.

Public API – CEngineSyncBase

Method	Description
`virtual ~CEngineSyncBase()`	Virtual destructor to ensure proper cleanup of derived synchronization implementations.
`static CEngineSyncBase* Create(...)`	Extended factory method allowing explicit engine type and scheduling configuration. Parameters: `streamName` – Source stream providing the hardware sync signal. `elementName` – Element within the stream to evaluate. `engType` – Engine synchronization implementation type (e.g., polling, interrupt-driven, edge-triggered). `affinity` – CPU affinity configuration for deterministic scheduling. `priority` – Thread scheduling priority (typically real-time). This overload enables strict control over execution determinism and runtime behavior.
`WaitSync()`	Blocks execution until the synchronization condition defined by `syncSignalFn` is met. This function is typically invoked once per frame inside the engine loop. It ensures that frame advancement occurs only after a valid external hardware synchronization event.

Operational Model

The engine initializes a synchronization instance via Create().
Start() activates the synchronization mechanism.
Each frame calls internally WaitSync() to align execution with hardware timing.
Stop() gracefully disables synchronization.

This model guarantees deterministic frame timing when integrating with external systems such as FPGA clocks, real-time controllers, or hardware-triggered acquisition systems.