96 lines
6.0 KiB
Markdown
96 lines
6.0 KiB
Markdown
---
|
|
source_files:
|
|
- Common/DTS.Common.DataModel/StateMachines/OverallArmStatusStateMachine.cs
|
|
generated_at: "2026-04-17T15:42:56.746110+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "5d72a0ae768f3eb3"
|
|
---
|
|
|
|
# Documentation: OverallArmStatusStateMachine
|
|
|
|
## 1. Purpose
|
|
|
|
The `OverallArmStatusStateMachine` class manages the lifecycle and state transitions for a Data Acquisition System's (DAS) arm status. It encapsulates complex state logic for recording operations, data downloading, flash clearing, and various waiting states (trigger, schedule, interval). The class uses the Stateless library to define valid state transitions and notifies subscribers via an event when state changes occur. This state machine appears to be part of a larger test/recording system where equipment must be armed, configured, and monitored through various operational phases.
|
|
|
|
## 2. Public Interface
|
|
|
|
### Constructor
|
|
```csharp
|
|
public OverallArmStatusStateMachine()
|
|
```
|
|
Initializes the state machine by resolving an `IEventAggregator` from the Prism container and calling the private `Initialize()` method. The initial state is set to `ArmStateMachineStates.States.CheckingForDAS`.
|
|
|
|
### Enum: Triggers
|
|
```csharp
|
|
public enum Triggers
|
|
```
|
|
Defines 35 trigger values that cause state transitions, including:
|
|
- `bFillingBuffer`, `CheckingForData`, `ConfigurationIsSet`, `DASNotFound`, `DataNeverDownloaded`, `Disarm`, `DoneRecording`, `Downloading`, `DownloadCleaningUp`, `DownloadFinished`, `Error`, `Faulted`, `FlashClear`, `GettingEventInfo`, `IDLE`, `IntervalRecording`, `NoDataToDownload`, `NonIntervalRecording`, `PostTestProcessing`, `ReadyForDownload`, `Rearming`, `Recording`, `RunButton`, `Streaming`, `WaitingForTrigger`, `WaitingForSchedule`, `WaitingForInterval`
|
|
- Single-character values: `a`, `c`, `d`, `e`, `h`, `n`, `rr`, `tt`, `uu`, `yy`
|
|
|
|
### Event: OverallStatusStateChange
|
|
```csharp
|
|
public event OverallStatusStateChangeDelegate OverallStatusStateChange;
|
|
```
|
|
Event raised when the state machine transitions to a new state. The delegate signature is:
|
|
```csharp
|
|
public delegate void OverallStatusStateChangeDelegate(ArmStateMachineStates.States previousState, ArmStateMachineStates.States nextState);
|
|
```
|
|
|
|
### Method: GetDASStatus
|
|
```csharp
|
|
public ArmStateMachineStates.States GetDASStatus()
|
|
```
|
|
Returns the current state stored in `CurrentOverallStatusState`.
|
|
|
|
### Method: FireTrigger
|
|
```csharp
|
|
public void FireTrigger(Triggers trigger, ArmStateMachineStates.States state)
|
|
```
|
|
Fires a trigger with an associated state parameter. Uses a switch statement to map triggers to their corresponding `TriggerWithParameters` instances and calls `overallArmStatusStateMachine.Fire()`. Catches and logs any exceptions without re-throwing.
|
|
|
|
**Handled triggers in switch:** `DASNotFound`, `NoDataToDownload`, `DataNeverDownloaded`, `DoneRecording`, `FlashClear`, `WaitingForTrigger`, `WaitingForSchedule`, `WaitingForInterval`, `Recording`, `PostTestProcessing`, `CheckingForData`, `GettingEventInfo`, `ReadyForDownload`, `Error`, `Streaming`, `Disarm`, `Rearming`
|
|
|
|
**Note:** `PostTestProcessing` trigger fires `DoneRecordingTrigger` internally.
|
|
|
|
## 3. Invariants
|
|
|
|
- The state machine always starts in `ArmStateMachineStates.States.CheckingForDAS`.
|
|
- `CurrentOverallStatusState` is only updated via `SetOverallStatus()` and only when the new state differs from the current state.
|
|
- State transitions are constrained by the Stateless configuration; invalid triggers will cause the Stateless library to throw (caught silently in `FireTrigger`).
|
|
- `SetOverallStatus()` is only called from `OnEntryFrom` handlers configured in the state machine.
|
|
- The `IEventAggregator` must be registered in the Prism container at construction time.
|
|
|
|
## 4. Dependencies
|
|
|
|
### External Dependencies
|
|
- **Stateless** - Third-party state machine library used for state transition management
|
|
- **Prism.Ioc** - `ContainerLocator` for service resolution
|
|
- **Prism.Events** - `IEventAggregator` interface (resolved but not used in visible code)
|
|
- **DTS.Common.Enums.TSRAIRGo** - Provides `ArmStateMachineStates.States` enum
|
|
- **DTS.Common.Utilities.Logging** - `APILogger` for logging state transitions and errors
|
|
|
|
### Internal Dependencies
|
|
- `ArmStateMachineStates.States` - External enum defining all possible states (referenced but not defined in this file)
|
|
|
|
### Consumers
|
|
- Unknown from source alone; consumers would subscribe to `OverallStatusStateChange` event and call `FireTrigger()`.
|
|
|
|
## 5. Gotchas
|
|
|
|
1. **Unused cryptic trigger values**: The `Triggers` enum contains unexplained single-character values (`a`, `c`, `d`, `e`, `h`, `n`, `rr`, `tt`, `uu`, `yy`) that are never referenced elsewhere in the code.
|
|
|
|
2. **Unimplemented trigger handling**: Several triggers in the enum are not handled in the `FireTrigger` switch statement, including: `bFillingBuffer`, `ConfigurationIsSet`, `DownloadCleaningUp`, `DownloadFinished`, `Faulted`, `IntervalRecording`, `NonIntervalRecording`, `RunButton`, and the single-character triggers. Firing these will silently do nothing (fall through to `default`).
|
|
|
|
3. **Error trigger not configured**: The `ErrorTrigger` field is initialized but no state configures transitions using it. Firing `Triggers.Error` will likely cause a Stateless exception (caught and logged silently).
|
|
|
|
4. **PostTestProcessing fires wrong trigger**: The `Triggers.PostTestProcessing` case fires `DoneRecordingTrigger` instead of a dedicated trigger. This appears to be a workaround or potential bug.
|
|
|
|
5. **Unused graph generation**: The `Initialize()` method generates a UML dot graph string but stores it in a local variable that is never used or exposed.
|
|
|
|
6. **Silent failure mode**: `FireTrigger()` catches all exceptions and only logs them; callers have no way to know if a trigger failed.
|
|
|
|
7. **Questionable parameter design**: As noted in the source comment, `FireTrigger` takes a `state` parameter, which the developer questioned: "why specify state here? shouldn't that be done based on current state/trigger?" This suggests potential confusion about the state machine's design intent.
|
|
|
|
8. **Unused IEventAggregator**: The `_eventAggregator` field is resolved but never used in the visible code. |