init

enriched-qwen3-coder-next/DataPRO/StateMachine.Tests/StatusAndParameters/Realtime.md

@@ -0,0 +1,87 @@
+---
+source_files:
+  - DataPRO/StateMachine.Tests/StatusAndParameters/Realtime/RealtimeStatusInformationShould.cs
+generated_at: "2026-04-16T04:24:39.879915+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "98f63d1d76a0b743"
+---
+
+# Realtime
+
+## Documentation: `RealtimeStatusInformation` Class
+
+### 1. Purpose  
+This class encapsulates state and control logic for managing real-time data acquisition operations within the DAS (Data Acquisition System) framework. It serves as a status tracker and coordinator for initiating and monitoring real-time sampling, exposing properties such as `CouldNotStartRealtime` and `IsInRealtime` to reflect the current operational state. It is used by test suites to validate behavior of real-time startup workflows and status reporting, and likely forms part of a larger state machine managing DAS communication sessions.
+
+### 2. Public Interface  
+The following members are *publicly accessible* based on usage in tests (i.e., `public` or `internal` with test visibility, but only these are referenced in the provided source):
+
+- **`RealtimeStatusInformation()`**  
+  *Constructor.* Initializes a new instance of the `RealtimeStatusInformation` class.
+
+- **`void StartRealtime(...)`**  
+  *Method.* Initiates a real-time acquisition session.  
+  **Signature (inferred from test call):**  
+  ```csharp
+  void StartRealtime(
+      List<IDASCommunication> dasList,
+      List<int> moduleIndices,
+      bool useSingleSampleMode,
+      int realtimeSampleRate,
+      int realtimeDelayBetweenPollsInMilliSecond,
+      bool allowMultipleSampleRealtime,
+      Action<double, double> SetRealtimeSampleRateAAF,
+      Action CompleteAction,
+      Dictionary<IDASCommunication, byte[]> idasToActiveChannels,
+      ServiceBase.Callback StartRealtimeCallback
+  );
+  ```
+  **Behavior:**  
+  Executes the real-time startup sequence. Based on the test assertion, this method *always* sets `CouldNotStartRealtime` to `true` after invocation in the current implementation (suggesting either incomplete implementation, a known failure mode, or intentional test stubbing). The method triggers callbacks (`CompleteAction`, `StartRealtimeCallback`) and passes parameters to `SetRealtimeSampleRateAAF`.
+
+- **`bool CouldNotStartRealtime { get; }`**  
+  *Read-only property.* Indicates whether real-time acquisition failed to start.  
+  **Behavior:**  
+  Returns `true` after `StartRealtime` is invoked (per test assertion), regardless of actual success/failure semantics. Its value is likely set internally during `StartRealtime`.
+
+- **`bool IsInRealtime { get; }`**  
+  *Read-only property.* Indicates whether the system is currently in a real-time acquisition state.  
+  **Behavior:**  
+  Returns `false` for a newly constructed instance (per test). Likely updated during `StartRealtime` and/or `StopRealtime` (not shown here), but current source only confirms initial state.
+
+> **Note:** No other public methods, properties, or fields are referenced or observable in the provided test file.
+
+### 3. Invariants  
+- `CouldNotStartRealtime` is set to `true` *immediately after* `StartRealtime` completes (as verified by test assertion).  
+- `IsInRealtime` is `false` for a freshly instantiated `RealtimeStatusInformation` object.  
+- The `StartRealtime` method requires non-null inputs for `dasList`, `moduleIndices`, `idasToActiveChannels`, `SetRealtimeSampleRateAAF`, `CompleteAction`, and `StartRealtimeCallback`; passing `null` may cause runtime exceptions (not validated in tests).  
+- `moduleIndices` must contain indices corresponding to valid entries in `dasList` (e.g., `moduleIndices[0] == 0` maps to `dasList[0]`), as implied by test setup.
+
+### 4. Dependencies  
+- **Direct Dependencies (from imports):**  
+  - `DTS.Common.Interface.DASFactory.IDASCommunication` – Interface for DAS communication abstraction.  
+  - `DTS.DASLib.Service.ServiceBase` – Provides `ServiceBase.Callback` delegate and `CallbackData` type.  
+  - `DTS.DASLib.Service.StateMachine` – Likely contains `RealtimeStatusInformation` and related state machine components.  
+  - `NSubstitute` – mocking framework (test-only).  
+  - `NUnit` – test framework (test-only).  
+
+- **Inferred Usage:**  
+  - `IDASCommunication` instances are used to represent physical/logical DAS devices.  
+  - `idasToActiveChannels` maps each `IDASCommunication` to a `byte[]` (likely channel bitmask).  
+  - `SetRealtimeSampleRateAAF` is a callback to configure AAF (Anti-Aliasing Filter) parameters.  
+  - `ServiceBase.Callback` is used for progress/status updates during acquisition (`NewData`, `AllFinished`).  
+
+- **Depended upon by:**  
+  - Test suite (`StateMachine.Tests`) – sole consumer in provided source.  
+  - Likely used by higher-level state machine components (e.g., in `DTS.DASLib.Service.StateMachine`) not shown here.
+
+### 5. Gotchas  
+- **`CouldNotStartRealtime` always `true` after `StartRealtime`**: The test asserts this unconditionally, suggesting either incomplete implementation, intentional stubbing for testing, or a known limitation where real-time startup *always* fails in the current build. This is likely a placeholder or work-in-progress behavior.  
+- **No `StopRealtime` or reset mechanism visible**: The class exposes no method to clear `CouldNotStartRealtime` or transition `IsInRealtime` to `true`, implying state may be sticky or managed externally.  
+- **Callback semantics not fully specified**: While `StartRealtimeCallback` is invoked with `CallbackData`, the test only logs status; actual data handling, error reporting, or cancellation behavior is not documented here.  
+- **No validation on `moduleIndices` vs. `dasList` length**: Passing mismatched indices (e.g., `moduleIndices.Count != dasList.Count`) may cause runtime errors (e.g., `IndexOutOfRangeException`).  
+- **Hardcoded test values**: `realtimeDelayBetweenPollsInMilliSecond = 4` and `realtimeSampleRate = 1000` are used in tests; their validity (e.g., minimum/maximum ranges) is not enforced in the test and may be undocumented.  
+- **No thread-safety guarantees**: The class is used synchronously in tests; concurrent access may cause race conditions (not addressed in source).  
+
+> **Note:** Since only test code is provided, internal implementation details (e.g., private fields, state transitions) are unknown. Behavior beyond what is exercised in tests is speculative.