From 61ba2dcf4d43983bbe459d97a8339780e0078902 Mon Sep 17 00:00:00 2001 From: Eric Flumerfelt Date: Mon, 26 Aug 2024 12:23:46 -0500 Subject: [PATCH] Add more detail on the motivation for Action Plans, and note that the FSMCommand objects should be treated as external inputs. --- docs/ActionPlans.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/ActionPlans.md b/docs/ActionPlans.md index 7b70f86..d8ecfbe 100755 --- a/docs/ActionPlans.md +++ b/docs/ActionPlans.md @@ -4,6 +4,8 @@ An ActionPlan defines a series of ActionSteps, each one consisting of a set of DAQModule classes to run the command on. Each ActionPlan is associated with a FSMCommand object, and is run by the appliction when it recieves the corresponding command. If a command is received and no ActionPlan is defined, the application currently runs a "dummy" ActionPlan consisting of a single step where registered Actions matching the command name are all run in parallel. +Action Plans allow for much finer-grained control over the execution of a command within an application, allowing for modules that have dependencies on one another to execute their commands correctly. It also introduces parallelization of command execution within each step, which helps with certain time-consuming module commands (e.g. configuring hardware on a link). The current implmentation uses std::future objects and a catch-all threading pattern to ensure that errors executing steps within an action plan do not lead to program crashes. + ## Defining an ActionPlan ActionPlans are defined in configuration using these objects: @@ -22,7 +24,7 @@ ActionPlans are defined in configuration using these objects: 1. ActionPlan relates a set of ActionSteps to a FSMCommand instance. 1. ActionStep lists the module types to run in parallel at a given point in the sequence -ActionPlans are validated by the application to ensure that every module type has registered methods corresponding to the command linked to the ActionPlan. +ActionPlans are validated by the application to ensure that every module type has registered methods corresponding to the command linked to the ActionPlan. Note that FSMCommand objects are usually defined by the CCM and included in a fsm.data.xml OKS database. ### Example test/config/appfwk.data.xml @@ -50,6 +52,8 @@ The DAQModuleManager_test unit test defines several ActionPlans used within the ``` +Here, the FSMCommand is defined in the file because it is a non-standard command used for the purposes of this unit test. Normally, the FSMCommand instance would not be defined in the same location as the ActionPlan that uses it. + The ActionPlans are associated with the Application instance as follows: ```XML @@ -70,3 +74,4 @@ The ActionPlans are associated with the Application instance as follows: * DAQModules register their action methods in the same way as before, however the specification of valid states for an action has been removed * ActionSteps target module types, with the assumption that if multiple modules of the same class are present within an application, they will all run their defined action methods in unison (or at least within the same parallel processing step) +* ActionPlans refer to FSMCommand objects as defined by the CCM. New FSMCommands may be added, but should be integrated into the state machine in consultation with CCM experts.