127 lines
7.0 KiB
Markdown
127 lines
7.0 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/IService/StateMachine/StatusAndParameters/IStatusInfo.cs
|
||
- DataPRO/IService/StateMachine/StatusAndParameters/IStatusParameters.cs
|
||
- DataPRO/IService/StateMachine/StatusAndParameters/GlobalStatusParameters.cs
|
||
- DataPRO/IService/StateMachine/StatusAndParameters/Status.cs
|
||
- DataPRO/IService/StateMachine/StatusAndParameters/GlobalStatusInformation.cs
|
||
generated_at: "2026-04-16T04:00:12.173977+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "9b91ae827f1dd2a6"
|
||
---
|
||
|
||
# StatusAndParameters
|
||
|
||
## Documentation: State Machine Status and Parameters Module
|
||
|
||
---
|
||
|
||
### 1. Purpose
|
||
This module defines the core data structures and interfaces for tracking and managing the runtime state and configuration parameters of a distributed acquisition system (DAS) within the state machine framework. It provides typed containers for *status information* (read-only or observation-oriented state, e.g., device presence in certain operational modes) and *status parameters* (configurable settings that influence behavior, e.g., multicast or auto-sense flags). The `Status` class aggregates all such state and parameter objects into a single, resettable snapshot used by the state machine to make decisions and coordinate subsystems.
|
||
|
||
---
|
||
|
||
### 2. Public Interface
|
||
|
||
#### Interfaces
|
||
- **`IStatusInfo`**
|
||
```csharp
|
||
void Reset();
|
||
```
|
||
Marker interface for status information types that support resetting to default state. No behavior beyond `Reset()` is defined here.
|
||
|
||
- **`IStatusParameters`**
|
||
```csharp
|
||
void Reset();
|
||
```
|
||
Marker interface for status parameter types that support resetting to default values. No behavior beyond `Reset()` is defined here.
|
||
|
||
#### Concrete Classes
|
||
|
||
- **`GlobalStatusParameters`** *(implements `IStatusParameters`)*
|
||
```csharp
|
||
public bool AllowUDPMulticast { get; set; } = true;
|
||
public bool DisableAutoSense { get; set; } = SensorConstants.DisableAutoSense;
|
||
public void Reset();
|
||
```
|
||
Holds global configuration flags. `Reset()` restores `AllowUDPMulticast` to `true` and `DisableAutoSense` to `SensorConstants.DisableAutoSense`.
|
||
|
||
- **`Status`** *(aggregate container)*
|
||
```csharp
|
||
public HardwareDiscoveryParameters HardwareDiscoveryParams;
|
||
public HardwareDiscoveryStatusInfo HardwareDiscoveryStatusInfo;
|
||
public GlobalStatusInformation GlobalStatusInformation;
|
||
public GlobalStatusParameters GlobalStatusParameters;
|
||
public ConfigureStatusInformation ConfigureStatus;
|
||
public ConfigureStatusParameters ConfigureParameters;
|
||
public RealtimeStatusInformation RealtimeStatus;
|
||
public RealtimeParameters RealtimeParams;
|
||
public DiagnoseParameters DiagnoseParams;
|
||
public DownloadParameters DownloadParams;
|
||
public DownloadStatusInformation DownloadStatusInfo;
|
||
public void Reset();
|
||
```
|
||
Central state container. `Reset()` invokes `Reset()` on all contained sub-objects *except* `DownloadStatusInfo` and `DownloadParams` (note: these are omitted from `Reset()`).
|
||
> ⚠️ **Observed omission**: `DownloadStatusInfo.Reset()` and `DownloadParams.Reset()` are *not* called in `Status.Reset()`, despite both being declared as fields.
|
||
|
||
- **`GlobalStatusInformation`** *(implements `IStatusInfo`)*
|
||
```csharp
|
||
public IDASCommunication[] GetUnitsInRealtime();
|
||
public void AddUnitInRealtime(IDASCommunication device);
|
||
public IDASCommunication[] GetUnitsInArm();
|
||
public void AddUnitInArm(IDASCommunication device);
|
||
public IDASCommunication[] GetUnitsAtLowPower();
|
||
public void AddUnitAtLowPower(IDASCommunication das);
|
||
public IDASCommunication[] GetUnitsAtHighPower();
|
||
public void AddUnitAtHighPower(IDASCommunication das);
|
||
public bool ExcitationOn { get; set; } = false;
|
||
public void Reset();
|
||
```
|
||
Tracks device presence and power/excitation state.
|
||
- `AddUnitInRealtime`, `AddUnitInArm`, `AddUnitAtLowPower`, `AddUnitAtHighPower` are idempotent (no-op if device already present).
|
||
- `AddUnitAtLowPower` removes device from `_unitsAtHighPower` if present.
|
||
- `AddUnitAtHighPower` removes device from `_unitsAtLowPower` if present.
|
||
- `Reset()` clears all device lists and sets `ExcitationOn = false`.
|
||
|
||
---
|
||
|
||
### 3. Invariants
|
||
|
||
- **Thread Safety**: All list-modifying operations in `GlobalStatusInformation` are guarded by a private static `lock (MyLock)`. Reads via `Get*()` methods are also lock-protected.
|
||
- **Mutual Exclusivity**: A device cannot be simultaneously in `_unitsAtLowPower` and `_unitsAtHighPower`. Adding to one list removes it from the other.
|
||
- **Idempotency**: `AddUnit*()` methods silently ignore duplicate additions (checked via `Contains()` before adding).
|
||
- **Reset Scope**: `Status.Reset()` does *not* reset `DownloadStatusInfo` or `DownloadParameters` (per source code).
|
||
- **Default Values**:
|
||
- `GlobalStatusParameters.AllowUDPMulticast` defaults to `true`.
|
||
- `GlobalStatusParameters.DisableAutoSense` defaults to `SensorConstants.DisableAutoSense`.
|
||
- `GlobalStatusInformation.ExcitationOn` defaults to `false`.
|
||
|
||
---
|
||
|
||
### 4. Dependencies
|
||
|
||
#### Imports/References
|
||
- **`DTS.Common.Enums.Sensors`**
|
||
Used in `GlobalStatusParameters` to initialize `DisableAutoSense` via `SensorConstants.DisableAutoSense`.
|
||
- **`DTS.Common.Interface.DASFactory`**
|
||
Used in `GlobalStatusInformation` for the `IDASCommunication` interface (device abstraction).
|
||
|
||
#### Consumed By
|
||
- The state machine logic (implied by namespace `DTS.DASLib.Service.StateMachine`).
|
||
- Any component needing to inspect or update device status (e.g., `Status` instance likely passed to state handlers).
|
||
|
||
#### Consumed By (Inferred)
|
||
- `GlobalStatusInformation`’s `IDASCommunication` usage implies integration with a device communication layer (e.g., factory-created units implementing `IDASCommunication`).
|
||
|
||
---
|
||
|
||
### 5. Gotchas
|
||
|
||
- **Incomplete Reset**: `Status.Reset()` omits `DownloadStatusInfo` and `DownloadParameters`. This is likely unintentional (both have `Reset()` methods per naming convention), and may cause stale download state to persist across resets.
|
||
- **No Removal Methods**: `GlobalStatusInformation` lacks explicit `RemoveUnit*()` methods. Devices are only removed via `Reset()` or implicitly via `AddUnitAtLowPower`/`AddUnitAtHighPower` (which remove from the *opposite* power list). There is no way to remove a device from `Realtime` or `Arm` lists except via `Reset()`.
|
||
- **Static Lock Scope**: The `MyLock` object is `static`, meaning all instances of `GlobalStatusInformation` share the same lock. This could cause contention if multiple `GlobalStatusInformation` instances are used concurrently (though only one is used via `Status.GlobalStatusInformation`).
|
||
- **No Validation in `Add*()`**: Methods like `AddUnitInRealtime` do not validate device state consistency (e.g., allowing a device to be added to both `Realtime` and `Arm` simultaneously is permitted).
|
||
- **`DisableAutoSense` Initialization**: Default value depends on `SensorConstants.DisableAutoSense`, whose value is not visible here. Its semantics (e.g., `true` = disable auto-sense?) must be verified in `DTS.Common.Enums.Sensors`.
|
||
|
||
None identified beyond those above. |