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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/StateMachine.Tests/StatusAndParameters/GlobalStatusInformationShould.cs	2026-04-16T04:24:23.201570+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.