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

---
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<IDASCommunication> GetUnitsInRealtime()`**  
  Returns a *copy* (as `List<IDASCommunication>`) 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<IDASCommunication> 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<IDASCommunication> 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<IDASCommunication> 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<T>`** — 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<IDASCommunication>` — *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.*