--- source_files: - DataPRO/StateMachine.Tests/StatusAndParameters/GlobalStatusInformationShould.cs generated_at: "2026-04-16T04:24:23.201570+00:00" model: "Qwen/Qwen3-Coder-Next-FP8" schema_version: 1 sha256: "cdc9e7fc7b8b72ec" --- # StatusAndParameters ## Documentation: `GlobalStatusInformation` Class ### 1. Purpose The `GlobalStatusInformation` class serves as a centralized in-memory registry for tracking the current state and membership of communication-enabled devices (`IDASCommunication` instances) across four distinct operational contexts: *realtime*, *arm*, *low power*, and *high power*. It maintains disjoint sets of devices per context and enforces uniqueness per context (i.e., a device instance may appear in at most one context at a time). This class is used within the state machine logic to manage and query device status during system operation, particularly during initialization, reconfiguration, or power-state transitions. --- ### 2. Public Interface #### `class GlobalStatusInformation` A concrete class (no interface declaration visible in test file) managing device groupings by operational context. ##### Methods - **`List GetUnitsInRealtime()`** Returns a *copy* (as `List`) of the current set of devices registered in the *realtime* context. Initially empty. - **`void AddUnitInRealtime(IDASCommunication device)`** Adds the given `device` to the *realtime* set *if not already present* in that set. Does *not* remove the device from other contexts (e.g., *arm*, *low power*, *high power*). → *Note: Tests confirm uniqueness is enforced per context only.* - **`List GetUnitsInArm()`** Returns a *copy* of the current set of devices registered in the *arm* context. Initially empty. - **`void AddUnitInArm(IDASCommunication device)`** Adds the given `device` to the *arm* set *if not already present* in that set. Does *not* remove the device from other contexts. - **`List GetUnitsAtLowPower()`** Returns a *copy* of the current set of devices registered in the *low power* context. Initially empty. - **`void AddUnitAtLowPower(IDASCommunication device)`** Adds the given `device` to the *low power* set *if not already present* in that set. → *Crucially*, if the same device instance is *already* in the *high power* set, it is **automatically removed** from *high power* before being added to *low power*. → Tests confirm this *mutual exclusion* only between *low power* and *high power*. - **`List GetUnitsAtHighPower()`** Returns a *copy* of the current set of devices registered in the *high power* context. Initially empty. - **`void AddUnitAtHighPower(IDASCommunication device)`** Adds the given `device` to the *high power* set *if not already present* in that set. → *Crucially*, if the same device instance is *already* in the *low power* set, it is **automatically removed** from *low power* before being added to *high power*. → Tests confirm this *mutual exclusion* only between *low power* and *high power*. - **`void Reset()`** Clears *all* device collections (realtime, arm, low power, high power) and sets `ExcitationOn` to `false`. Does *not* dispose or modify the `IDASCommunication` instances themselves. ##### Properties - **`bool ExcitationOn`** A boolean flag indicating whether excitation (likely a measurement or calibration signal) is active. Initialized to `false`. Cleared to `false` on `Reset()`. --- ### 3. Invariants - **Contextual Uniqueness (Per Context)** Within any *single* context (e.g., *realtime*, *arm*, *low power*, *high power*), a given `IDASCommunication` instance may appear **at most once**. Attempting to add the same instance again has no effect. - **Mutual Exclusivity (Low Power ↔ High Power)** A device instance **cannot be in both *low power* and *high power* simultaneously**. Adding a device to one automatically removes it from the other *if present*. → This is the *only* cross-context constraint enforced. - **No Cross-Context Exclusivity** A device may appear in *any combination* of the following contexts: *realtime*, *arm*, *low power*, *high power* — *except* the *low power*/*high power* pair. Example: A device may be in *realtime* + *low power* + *arm* concurrently. - **State Reset** `Reset()` guarantees all device collections are empty and `ExcitationOn` is `false`. --- ### 4. Dependencies #### Dependencies *on* `GlobalStatusInformation` - **`DTS.DASLib.Service.StateMachine`** (namespace) — The class resides in this namespace, implying integration with the state machine subsystem. - **`DTS.Common.Interface.DASFactory.IDASCommunication`** — The core interface for device communication objects used as inputs/outputs. - **`NSubstitute`** — Used in tests for mocking `IDASCommunication`; not a runtime dependency. #### Dependencies *of* `GlobalStatusInformation` - **`DTS.Common.Interface.DASFactory.IDASCommunication`** — Required for method signatures. - **`System.Collections.Generic.List`** — Used as return type for all `Get*()` methods. #### Inferred Consumers - State machine logic (e.g., transitions, state queries) — implied by test namespace `StateMachine.Tests.StatusAndParameters`. - Any module needing to track or query device presence in specific operational modes. --- ### 5. Gotchas - **Shallow Copies Returned** `GetUnits*()` methods return `List` — *not* a defensive copy of the underlying collection’s *contents*. Modifications to the returned list (e.g., `Clear()`, `Remove()`) will affect the internal state. Tests do *not* verify immutability of the returned list, and the class does not clone devices. → **Recommendation**: Callers should treat the returned list as read-only or clone it explicitly. - **Only Low/High Power Are Mutually Exclusive** Developers may incorrectly assume *all* contexts are disjoint. In reality, a device can be in *realtime* and *low power* simultaneously — only *low power* ↔ *high power* are mutually exclusive. - **Reference Equality Used for Uniqueness** Uniqueness is enforced via *reference equality* (e.g., `thirdDevice = secondDevice` in tests). Two distinct `IDASCommunication` instances with identical `SerialNumber` are treated as different devices. → Serial number is *not* used for deduplication. - **No Explicit Thread Safety** No synchronization primitives or concurrency guarantees are evident. Concurrent access may lead to race conditions. - **No Validation on `device` Parameter** Methods accept `null` without visible checks (tests use mocked non-null devices). Passing `null` may cause `NullReferenceException` (e.g., accessing `.SerialNumber`). → *Not explicitly tested; behavior undefined.* - **`Reset()` Does Not Notify Consumers** Clearing state via `Reset()` has no side effects (e.g., no events, callbacks). Downstream logic relying on `GlobalStatusInformation` state must re-query after `Reset()`. --- *Documentation derived solely from test file `GlobalStatusInformationShould.cs`. Implementation details (e.g., internal storage, constructor) are not visible and thus not documented.*