DP44/enriched-qwen3-coder-next/DataPRO/IService/StateMachine/States.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/IService/StateMachine/States/Arm.cs DataPRO/IService/StateMachine/States/Arming.cs DataPRO/IService/StateMachine/States/Realtime.cs DataPRO/IService/StateMachine/States/Download.cs DataPRO/IService/StateMachine/States/HardwareDiscovery.cs DataPRO/IService/StateMachine/States/Prepare.cs DataPRO/IService/StateMachine/States/ConfigureStart.cs DataPRO/IService/StateMachine/States/RealtimeStart.cs DataPRO/IService/StateMachine/States/Configure.cs DataPRO/IService/StateMachine/States/Diagnose.cs DataPRO/IService/StateMachine/States/DownloadStart.cs DataPRO/IService/StateMachine/States/HardwareDiscoveryStart.cs	2026-04-16T04:00:35.991960+00:00	Qwen/Qwen3-Coder-Next-FP8	1	dc1b1b8c07850591

States

Documentation: StateMachine States Module

1. Purpose

This module defines the concrete state implementations for the DAS (Data Acquisition System) service state machine. Each class represents a terminal or selector state in the state transition graph, encapsulating entry actions and transition logic. The states manage transitions between operational modes such as hardware discovery, configuration, arming, real-time acquisition, and data download. The module serves as the behavioral core of the state machine, where transitions are determined by runtime status flags and configuration parameters.

2. Public Interface

All classes inherit from DASState (or DASStateSelector for selector states) in the DTS.DASLib.Service.StateMachine namespace. Only Realtime, ConfigureStart, RealtimeStart, Configure, Diagnose, DownloadStart, and HardwareDiscoveryStart are public; the rest are internal.

Terminal States (non-selector, inherit DASState)

• public class Realtime : DASState
  Represents the active real-time acquisition state. Returns State.Realtime via the State property. No custom entry action.

• internal class Arm : DASState
  Represents the armed (ready but not yet acquiring) state. Returns State.Arm.

• internal class Arming : DASState
  Represents the transitional arming state. Returns State.Arming.

• internal class Download : DASState
  Represents the data download state. Returns State.Download.

• internal class HardwareDiscovery : DASState
  Represents the hardware discovery state. Returns State.HardwareDiscovery.

• internal class Prepare : DASState
  Represents the prepare state. Overrides OnEntry to invoke PrepareDASFactory, which detaches all devices and clears host name arrays in DASFactory (if non-null). Returns State.Prepare.

Selector States (inherit DASStateSelector)

• public class ConfigureStart : DASStateSelector
  Entry action: ApplyConfig, which calls Status.ConfigureStatus.ApplyConfig().
  Selector logic: Always returns States.Instance.Diagnose.
  Returns State.ConfigureStart.

• public class RealtimeStart : DASStateSelector
  Entry action: Start, which calls Status.RealtimeStatus.StartRealtime().
  Selector logic:

  • If Status.RealtimeStatus.CouldNotStartRealtime is true → returns States.Instance.RealtimeStart (retry loop).
  • Else → returns States.Instance.Realtime.
    Returns State.RealtimeStart.

• public class Configure : DASStateSelector
  Selector logic:

  • AllowApplyConfig() currently always returns true (placeholder logic).
  • If true → returns States.Instance.ConfigureStart.
  • Else → returns States.Instance.Configure (self-loop).
    Returns State.Configure.

• public class Diagnose : DASStateSelector
  Selector logic:

  • Returns States.Instance.RealtimeStart if either:
    (a) Status.DiagnoseParams.ProceedToRealtimeWhenDone && Status.DiagnoseParams.AllUnitsPassedDiagnostic, or
    (b) Status.DiagnoseParams.ProceedToRealtimeWhenDone && !Status.DiagnoseParams.RequireAllUnitsPassDiagnostic.
  • Else → returns States.Instance.Diagnose (self-loop).
    Returns State.Diagnose.

• public class DownloadStart : DASStateSelector
  Entry action: Start, which calls Status.DownloadStatusInfo.Download().
  Selector logic:

  • Returns States.Instance.Prepare if CanTransitToPrepare() is true:
    Status.DownloadParams.ProceedWhenDone && (Status.DownloadStatusInfo.AllDASFinished || !Status.DownloadParams.RequireAllDASFinish).
  • Else → returns States.Instance.Download (self-loop).
    Returns State.DownloadStart.

• public class HardwareDiscoveryStart : DASStateSelector
  Entry action: Start, which calls either RequeryDevice() or Ping() on Status.HardwareDiscoveryStatusInfo, depending on whether Status.HardwareDiscoveryParams.RequeryDevice is non-null.
  Selector logic (evaluated in order):

  • CanTransitToDownload() → returns States.Instance.Download
  • CanTransitToConfigure() → returns States.Instance.Configure
  • CanTransitToArm() → returns States.Instance.Arm
  • Else → returns States.Instance.HardwareDiscovery (self-loop)
    Where:
  • CanTransitToConfigure(): Status.HardwareDiscoveryParams.ProceedWhenDone && (Status.HardwareDiscoveryStatusInfo.AllDASFound || !Status.HardwareDiscoveryParams.RequireAllDASFound)
  • CanTransitToArm(): Status.HardwareDiscoveryParams.ProceedWhenDone && Status.HardwareDiscoveryStatusInfo.SomeUnitsInArmState
  • CanTransitToDownload(): CanTransitToConfigure() && Status.HardwareDiscoveryParams.GoToDownload
    Returns State.HardwareDiscoveryStart.

3. Invariants

• Every state class must override the State property to return its corresponding State enum value (e.g., State.Prepare, State.Realtime).
• Selector states (DASStateSelector subclasses) must implement StateSelector() to return an IDASState (typically via States.Instance.<StateName>).
• Terminal states (DASState subclasses) may optionally override OnEntry to define entry behavior; if not overridden, no entry action is executed.
• The OnEntry action (if present) must call OnEnterState() as its first operation (observed in Prepare, ConfigureStart, RealtimeStart, DownloadStart, HardwareDiscoveryStart).
• Transition decisions in selector states are based solely on Status.* properties and Status.*Params configuration objects.
• No state class performs side effects outside of OnEntry or StateSelector().

4. Dependencies

• Internal dependencies (from source):

  • DASState and DASStateSelector base classes (not shown, but implied by inheritance).
  • State enum (used in State property overrides).
  • States.Instance singleton (used to reference other states, e.g., States.Instance.Diagnose).
  • Status object with nested properties:
    • ConfigureStatus, RealtimeStatus, DiagnoseParams, DownloadStatusInfo, DownloadParams, HardwareDiscoveryParams, HardwareDiscoveryStatusInfo.
  • DASFactory (used in Prepare.PrepareDASFactory(); assumed to be a member of the base DASState class or accessible via this).

• External dependencies (inferred):

  • System and related namespaces (e.g., System.Threading.Tasks).
  • Likely depends on a larger DTS.DASLib.Service assembly containing Status, States, and base state classes.

5. Gotchas

• Incomplete logic in Configure.AllowApplyConfig(): Currently always returns true; no actual validation of channel resolution or placement is implemented despite comments indicating intent.
• Selector state ordering matters: In HardwareDiscoveryStart, transitions are evaluated in a specific order (Download → Configure → Arm → self-loop). Changing this order could alter behavior.
• Self-loops may cause infinite loops: States like Configure, Diagnose, Download, and HardwareDiscovery can loop to themselves if conditions are not met; external triggers or status changes are required to exit.
• Ambiguous DASFactory usage: PrepareDASFactory() references DASFactory without clear scoping—assumed to be a member of the base class, but not declared in the provided source.
• No explicit error handling: Entry actions (e.g., StartRealtime(), Download()) may throw exceptions; no try/catch is visible in the source.
• RealtimeStart selector logic may retry indefinitely: If CouldNotStartRealtime remains true, the state machine will loop back to RealtimeStart without backoff or failure reporting.
• RequeryDevice() vs Ping() behavior: The condition null != Status.HardwareDiscoveryParams.RequeryDevice suggests RequeryDevice is a delegate or method group, but its type and semantics are not evident from this file.