Line data Source code
1 : #ifndef artdaq_ExternalComms_CommanderInterface_hh
2 : #define artdaq_ExternalComms_CommanderInterface_hh
3 :
4 : #include "artdaq/Application/Commandable.hh"
5 :
6 : #include "fhiclcpp/ParameterSet.h"
7 : #include "fhiclcpp/types/Atom.h"
8 : #include "fhiclcpp/types/Comment.h"
9 : #include "fhiclcpp/types/ConfigurationTable.h"
10 : #include "fhiclcpp/types/Name.h"
11 :
12 : #include "cetlib/compiler_macros.h"
13 :
14 : #include <atomic>
15 : #include <memory>
16 : #include <string>
17 :
18 : namespace artdaq {
19 : /**
20 : * \brief This interface defines the functions used to transfer data between artdaq applications.
21 : */
22 : class CommanderInterface
23 : {
24 : public:
25 : /// <summary>
26 : /// Configuration of the CommanderInterface. May be used for parameter validation
27 : /// </summary>
28 : struct Config
29 : {
30 : /// "id" (Default: 0): Integer ID number of this Commandable.May be constrained by plugin types(i.e.XMLRPC port number).
31 : fhicl::Atom<int> id{fhicl::Name{"id"}, fhicl::Comment{"The unique ID associated with this Commander plugin. (ex. XMLRPC Port number)"}, 0};
32 : /// "commanderPluginType" (REQUIRED): The type of Commander plugin to load
33 : fhicl::Atom<std::string> commanderPluginType{fhicl::Name{"commanderPluginType"}, fhicl::Comment{"String identifying the name of the CommanderInterface plugin to load"}};
34 : };
35 : /// Used for ParameterSet validation (if desired)
36 : using Parameters = fhicl::WrappedTable<Config>;
37 :
38 : /**
39 : * \brief CommanderInterface Constructor
40 : * \param ps ParameterSet used for configuring the CommanderInterface. See artdaq::CommanderInterface::Config
41 : * \param commandable artdaq::Commandable object to send transition commands to
42 : */
43 0 : CommanderInterface(const fhicl::ParameterSet& ps, artdaq::Commandable& commandable)
44 0 : : _commandable(commandable)
45 0 : , _id(ps.get<int>("id", 0))
46 0 : {}
47 :
48 : /**
49 : * \brief Copy Constructor is deleted
50 : */
51 : CommanderInterface(const CommanderInterface&) = delete;
52 :
53 : /**
54 : * \brief Copy Assignment operator is deleted
55 : * \return CommanderInterface Copy
56 : */
57 : CommanderInterface& operator=(const CommanderInterface&) = delete;
58 :
59 : /**
60 : * \brief Default virtual Destructor
61 : */
62 : virtual ~CommanderInterface();
63 :
64 : /// <summary>
65 : /// run_server is the main work loop for the Commander.
66 : ///
67 : /// This function is expected to block and persist for the entire run of the application.
68 : /// It should accept and handle the following commands (subject to state-machine constraints, see Commandable::legal_commands()):
69 : /// init
70 : /// soft_init
71 : /// reinit
72 : /// start
73 : /// pause
74 : /// resume
75 : /// stop
76 : /// shutdown
77 : /// status
78 : /// report
79 : /// legal_commands
80 : /// register_monitor
81 : /// unregister_monitor
82 : /// trace_get
83 : /// trace_set
84 : /// meta_command
85 : /// rollover_subrun
86 : /// add_config_archive_entry
87 : /// clear_config_archive
88 : ///
89 : /// See the send_* functions for more details on each command. Not all commands are valid for all applications/states.
90 : /// run_server should return a string indicating success or failure to the transport mechanism when it is done processing a command.
91 : /// </summary>
92 : virtual void run_server() = 0;
93 :
94 : /// <summary>
95 : /// Using the transport mechanism, send an init command
96 : ///
97 : /// The init command is accepted by all artdaq processes that are in the booted state.
98 : /// It expects a ParameterSet for configuration, a timeout, and a timestamp.
99 : /// </summary>
100 : /// <param name="ps">ParameterSet for the command</param>
101 : /// <param name="timeout">Timeout for the command</param>
102 : /// <param name="timestamp">Timestamp of the command</param>
103 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
104 : virtual std::string send_init(fhicl::ParameterSet const& ps, uint64_t timeout, uint64_t timestamp);
105 :
106 : /// <summary>
107 : /// Using the transport mechanism, send a soft_init command
108 : ///
109 : /// The soft_init command is accepted by all artdaq processes that are in the booted state.
110 : /// It expects a ParameterSet for configuration, a timeout, and a timestamp.
111 : /// </summary>
112 : /// <param name="ps">ParameterSet for the command</param>
113 : /// <param name="timeout">Timeout for the command</param>
114 : /// <param name="timestamp">Timestamp of the command</param>
115 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
116 : virtual std::string send_soft_init(fhicl::ParameterSet const& ps, uint64_t timeout, uint64_t timestamp);
117 :
118 : /// <summary>
119 : /// Using the transport mechanism, send a reinit command
120 : ///
121 : /// The reinit command is accepted by all artdaq processes.
122 : /// It expects a ParameterSet for configuration, a timeout, and a timestamp.
123 : /// </summary>
124 : /// <param name="ps">ParameterSet for the command</param>
125 : /// <param name="timeout">Timeout for the command</param>
126 : /// <param name="timestamp">Timestamp of the command</param>
127 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
128 : virtual std::string send_reinit(fhicl::ParameterSet const& ps, uint64_t timeout, uint64_t timestamp);
129 :
130 : /// <summary>
131 : /// Using the transport mechanism, send a start command
132 : ///
133 : /// The start command starts a Run using the given run number.
134 : /// This command also accepts a timeout parameter and a timestamp parameter.
135 : /// </summary>
136 : /// <param name="runNumber">Run number of the new run</param>
137 : /// <param name="timeout">Timeout for the command</param>
138 : /// <param name="timestamp">Timestamp of the command</param>
139 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
140 : virtual std::string send_start(art::RunID runNumber, uint64_t timeout, uint64_t timestamp);
141 :
142 : /// <summary>
143 : /// Using the transport mechanism, send a pause command
144 : ///
145 : /// The pause command pauses a Run. When the run resumes, the subrun number will be incremented.
146 : /// This command accepts a timeout parameter and a timestamp parameter.
147 : /// </summary>
148 : /// <param name="timeout">Timeout for the command</param>
149 : /// <param name="timestamp">Timestamp of the command</param>
150 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
151 : virtual std::string send_pause(uint64_t timeout, uint64_t timestamp);
152 :
153 : /// <summary>
154 : /// Using the transport mechanism, send a resume command
155 : ///
156 : /// The resume command resumes a paused Run. When the run resumes, the subrun number will be incremented.
157 : /// This command accepts a timeout parameter and a timestamp parameter.
158 : /// </summary>
159 : /// <param name="timeout">Timeout for the command</param>
160 : /// <param name="timestamp">Timestamp of the command</param>
161 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
162 : virtual std::string send_resume(uint64_t timeout, uint64_t timestamp);
163 :
164 : /// <summary>
165 : /// Using the transport mechanism, send a stop command
166 : ///
167 : /// The stop command stops the current Run.
168 : /// This command accepts a timeout parameter and a timestamp parameter.
169 : /// </summary>
170 : /// <param name="timeout">Timeout for the command</param>
171 : /// <param name="timestamp">Timestamp of the command</param>
172 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
173 : virtual std::string send_stop(uint64_t timeout, uint64_t timestamp);
174 :
175 : /// <summary>
176 : /// Using the transport mechanism, send a shutdown command
177 : ///
178 : /// The shutdown command shuts down the artdaq process.
179 : /// This command accepts a timeout parameter.
180 : /// </summary>
181 : /// <param name="timeout">Timeout for the command</param>
182 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
183 : virtual std::string send_shutdown(uint64_t timeout);
184 :
185 : /// <summary>
186 : /// Using the transport mechanism, send a status command
187 : ///
188 : /// The status command returns the current status of the artdaq process.
189 : /// </summary>
190 : /// <returns>Command result: current status of the artdaq process</returns>
191 : virtual std::string send_status();
192 :
193 : /// <summary>
194 : /// Using the transport mechanism, send a report command
195 : ///
196 : /// The report command returns the current value of the requested reportable quantity.
197 : /// </summary>
198 : /// <param name="which">Reportable quantity to request</param>
199 : /// <returns>Command result: current value of the requested reportable quantity</returns>
200 : virtual std::string send_report(std::string const& which);
201 :
202 : /// <summary>
203 : /// Using the transport mechanism, send a legal_commands command
204 : ///
205 : /// This will query the artdaq process, and it will return the list of allowed transition commands from its current state.
206 : /// </summary>
207 : /// <returns>Command result: a list of allowed transition commands from its current state</returns>
208 : virtual std::string send_legal_commands();
209 :
210 : /// <summary>
211 : /// Using the transport mechanism, send a register_monitor command
212 : ///
213 : /// This will cause a Dispatcher to start an art process with the given FHiCL configuration string
214 : /// </summary>
215 : /// <param name="monitor_fhicl">FHiCL code used to configure the art process that the Dispatcher starts</param>
216 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
217 : virtual std::string send_register_monitor(std::string const& monitor_fhicl);
218 :
219 : /// <summary>
220 : /// Using the transport mechanism, send an unregister_monitor command
221 : ///
222 : /// This will cause a Dispatcher to stop sending data to the monitor identified by the given label
223 : /// </summary>
224 : /// <param name="label">Label of the monitor to unregister</param>
225 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
226 : virtual std::string send_unregister_monitor(std::string const& label);
227 :
228 : /// <summary>
229 : /// Using the transport mechanism, send an send_trace_get command
230 : ///
231 : /// This will cause the receiver to get the TRACE level masks for the given name
232 : /// Use name == "ALL" to get ALL names
233 : /// </summary>
234 : /// <param name="name">TRACE name to get the mask for ("ALL" to get all names)</param>
235 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
236 : virtual std::string send_trace_get(std::string const& name);
237 :
238 : /// <summary>
239 : /// Using the transport mechanism, send an send_trace_msgfacility_set command
240 : ///
241 : /// This will cause the receiver to set the given TRACE level mask for the given name to the given mask.
242 : /// Only the first character of the mask selection will be parsed, dial 'M' for Memory, or 'S' for Slow.
243 : /// Use name == "ALL" to set ALL names
244 : ///
245 : /// EXAMPLE: xmlrpc http://localhost:5235/RPC2 daq.trace_set s/M s/ALL s/0x12345
246 : ///
247 : /// </summary>
248 : /// <param name="name">TRACE name to set ("ALL" for all TRACE names)</param>
249 : /// <param name="type">Type of mask to set ('M', 'S', or 'T')</param>
250 : /// <param name="mask">64-bit mask, in string form</param>
251 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
252 : virtual std::string send_trace_set(std::string const& name, std::string const& type, std::string const& mask);
253 :
254 : /// <summary>
255 : /// Using the transport mechanism, send an send_meta_command command
256 : ///
257 : /// This will cause the receiver to run the given command with the given argument in user code
258 : /// </summary>
259 : /// <param name="command">Command name to send</param>
260 : /// <param name="argument">Argument for command</param>
261 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
262 : virtual std::string send_meta_command(std::string const& command, std::string const& argument);
263 :
264 : /// <summary>
265 : /// Using the transport mechanism, send a send_rollover_subrun command
266 : ///
267 : /// This will cause the receiver to rollover the subrun number at the given event. (Event with seqID == boundary will be in new subrun.)
268 : /// Should be sent to all EventBuilders before the given event is processed.
269 : /// </summary>
270 : /// <param name="seq">Sequence ID of new subrun</param>
271 : /// <param name="subrunNumber">Subrun number of the new subrun</param>
272 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
273 : virtual std::string send_rollover_subrun(uint64_t seq, uint32_t subrunNumber);
274 :
275 : /// <summary>
276 : /// Determine whether the Commander plugin is ready to accept commands
277 : /// </summary>
278 : /// <returns>True if running, false otherwise</returns>
279 2 : bool GetStatus() { return running_.load(); }
280 :
281 : /// <summary>
282 : /// Using the transport mechanism, send an add_config_archive_entry command
283 : ///
284 : /// This will cause the receiver to add the specified key and value to its list of
285 : /// configuration archive information, which is stored in the art/ROOT files that are
286 : /// written by various processes in the system.
287 : /// This command accepts configuration key and value strings.
288 : ///
289 : /// EXAMPLE: xmlrpc http://localhost:5235/RPC2 daq.add_config_archive_entry "EventBuilder1" "daq: {verbose: true}"
290 : /// </summary>
291 : /// <param name="key">Key in the archive</param>
292 : /// <param name="value">Value to store in the archive</param>
293 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
294 : virtual std::string add_config_archive_entry(std::string const& key, std::string const& value);
295 :
296 : /// <summary>
297 : /// Using the transport mechanism, send a clear_config_archive command
298 : ///
299 : /// This will cause the receiver to clear its list of configuration archive information.
300 : ///
301 : /// EXAMPLE: xmlrpc http://localhost:5235/RPC2 daq.clear_config_archive
302 : /// </summary>
303 : /// <returns>Command result: "SUCCESS" if succeeded</returns>
304 : virtual std::string clear_config_archive();
305 :
306 : private:
307 : CommanderInterface(CommanderInterface&&) = delete;
308 : CommanderInterface& operator=(CommanderInterface&&) = delete;
309 :
310 : public:
311 : /// <summary>
312 : /// Reference to the Commandable that this Commander Commands.
313 : /// </summary>
314 : artdaq::Commandable& _commandable;
315 :
316 : protected:
317 : int _id; ///< ID Number of this Commander
318 : std::atomic<bool> running_; ///< Whether the server is running and able to respond to requests
319 : };
320 : } // namespace artdaq
321 :
322 : #ifndef EXTERN_C_FUNC_DECLARE_START
323 : #define EXTERN_C_FUNC_DECLARE_START extern "C" {
324 : #endif
325 :
326 : #define DEFINE_ARTDAQ_COMMANDER(klass) \
327 : EXTERN_C_FUNC_DECLARE_START \
328 : std::unique_ptr<artdaq::CommanderInterface> make(fhicl::ParameterSet const& ps, \
329 : artdaq::Commandable& commandable) \
330 : { \
331 : return std::unique_ptr<artdaq::CommanderInterface>(new klass(ps, commandable)); \
332 : } \
333 : }
334 :
335 : #endif /* artdaq_ExternalComms_CommanderInterface.hh */
336 :
337 : // Local Variables:
338 : // mode: c++
339 : // End:
|
