125 lines
7.1 KiB
Markdown
125 lines
7.1 KiB
Markdown
---
|
||
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.* |