artdaq  3.12.07
CommandableFragmentGenerator.hh
1 #ifndef artdaq_Application_CommandableFragmentGenerator_hh
2 #define artdaq_Application_CommandableFragmentGenerator_hh
3 
4 #include "fhiclcpp/types/Sequence.h" // Must pre-empt fhiclcpp/types/Atom.h
5 
6 #include "TRACE/tracemf.h" // Pre-empt TRACE/trace.h from Fragment.hh.
7 #include "artdaq-core/Data/Fragment.hh"
8 
9 #include "artdaq-core/Plugins/FragmentGenerator.hh"
10 #include "artdaq/DAQrate/FragmentBuffer.hh"
11 #include "artdaq/DAQrate/RequestBuffer.hh"
12 
13 #include "fhiclcpp/types/Atom.h"
14 #include "fhiclcpp/types/Comment.h"
15 #include "fhiclcpp/types/ConfigurationTable.h"
16 #include "fhiclcpp/types/Name.h"
17 namespace fhicl {
18 class ParameterSet;
19 }
20 
21 #include <boost/thread.hpp>
22 
23 #include <array>
24 #include <atomic>
25 #include <chrono>
26 #include <condition_variable>
27 #include <list>
28 #include <memory>
29 #include <mutex>
30 #include <queue>
31 
32 // Socket Includes
33 #include <arpa/inet.h>
34 #include <netinet/in.h>
35 #include <sys/socket.h>
36 #include <sys/types.h>
37 #include <unistd.h>
38 
39 namespace artdaq {
40 
83 class CommandableFragmentGenerator : public FragmentGenerator
84 {
85 public:
89  struct Config
90  {
92  fhicl::Atom<std::string> generator_type{fhicl::Name{"generator"}, fhicl::Comment{"Name of the CommandableFragmentGenerator plugin to load"}};
94  fhicl::Atom<Fragment::type_t> expected_fragment_type{fhicl::Name{"expected_fragment_type"}, fhicl::Comment{"The type of Fragments this CFG will be generating. \"Empty\" will auto-detect type based on Fragments generated."}, Fragment::type_t(Fragment::EmptyFragmentType)};
96  fhicl::Atom<size_t> sleep_on_no_data_us{fhicl::Name{"sleep_on_no_data_us"}, fhicl::Comment{"How long to sleep after calling getNext_ if no data is returned"}, 0};
98  fhicl::Atom<bool> separate_monitoring_thread{fhicl::Name{"separate_monitoring_thread"}, fhicl::Comment{"Whether a thread that calls the checkHWStatus_ method should be created"}, false};
100  fhicl::Atom<int64_t> hardware_poll_interval_us{fhicl::Name{"hardware_poll_interval_us"}, fhicl::Comment{"If a separate monitoring thread is used, how often should it call checkHWStatus_"}, 0};
103  fhicl::Sequence<Fragment::fragment_id_t> fragment_ids{fhicl::Name("fragment_ids"), fhicl::Comment("A list of Fragment IDs created by this CommandableFragmentGenerator")};
106  fhicl::Atom<int> fragment_id{fhicl::Name{"fragment_id"}, fhicl::Comment{"The Fragment ID created by this CommandableFragmentGenerator"}, -99};
108  fhicl::Atom<int> sleep_on_stop_us{fhicl::Name{"sleep_on_stop_us"}, fhicl::Comment{"How long to sleep before returning when stop transition is called"}, 0};
109  };
111  using Parameters = fhicl::WrappedTable<Config>;
112 
117  explicit CommandableFragmentGenerator(const fhicl::ParameterSet& ps);
118 
125 
132  void joinThreads();
133 
139  bool getNext(FragmentPtrs& output) override final;
140 
144  void startMonitoringThread();
145 
149  void getMonitoringDataLoop();
150 
155  std::vector<Fragment::fragment_id_t> fragmentIDs() override
156  {
157  std::vector<Fragment::fragment_id_t> output;
158 
159  for (auto& id : expectedTypes_)
160  {
161  output.push_back(id.first);
162  }
163 
164  return output;
165  }
166 
171  size_t ev_counter() const { return ev_counter_.load(); }
172 
173  //
174  // State-machine related interface below.
175  //
176 
191  void StartCmd(int run, uint64_t timeout, uint64_t timestamp);
192 
202  void StopCmd(uint64_t timeout, uint64_t timestamp);
203 
213  void PauseCmd(uint64_t timeout, uint64_t timestamp);
214 
223  void ResumeCmd(uint64_t timeout, uint64_t timestamp);
224 
235  std::string ReportCmd(std::string const& which = "");
236 
241  virtual std::string metricsReportingInstanceName() const
242  {
243  return instance_name_for_metrics_;
244  }
245 
246  // The following functions are not yet implemented, and their
247  // signatures may be subject to change.
248 
249  // John F., 12/6/13 -- do we want Reset and Shutdown commands?
250  // Kurt B., 15-Feb-2014. For the moment, I suspect that we don't
251  // want a Shutdown command. FragmentGenerator instances are
252  // Constructed at Initialization time, and they are destructed
253  // at Shutdown time. So, any shutdown operations that need to be
254  // done should be put in the FragmentGenerator child class
255  // destructors. If we find that want shutdown (or initialization)
256  // operations that are different from destruction (construction),
257  // then we'll have to add InitCmd and ShutdownCmd methods.
258 
259  // virtual void ResetCmd() final {}
260  // virtual void ShutdownCmd() final {}
261 
266  bool exception() const { return exception_.load(); }
267 
274  virtual bool metaCommand(std::string const& command, std::string const& arg);
275 
280  void SetRequestBuffer(std::shared_ptr<RequestBuffer> buffer) { requestBuffer_ = buffer; }
281 
282  void SetFragmentBuffer(std::shared_ptr<FragmentBuffer> buffer) { fragmentBuffer_ = buffer; }
283 
284 protected:
285  // John F., 12/6/13 -- need to figure out which of these getter
286  // functions should be promoted to "public"
287 
288  // John F., 1/21/15 -- after more than a year, there hasn't been a
289  // single complaint that a CommandableFragmentGenerator-derived
290  // class hasn't allowed its users to access these quantities, so
291  // they're probably fine as is
292 
297  int run_number() const { return run_number_; }
302  int subrun_number() const { return subrun_number_; }
307  uint64_t timeout() const { return timeout_; }
312  uint64_t timestamp() const { return timestamp_; }
313 
319  artdaq::Fragment::fragment_id_t fragment_id() const
320  {
321  if (expectedTypes_.size() > 1) throw cet::exception("FragmentID") << "fragment_id() was called, indicating that Fragment Generator was expecting one and only one Fragment ID, but " << expectedTypes_.size() << " were declared!"; // NOLINT(cert-err60-cpp)
322  return (*expectedTypes_.begin()).first;
323  }
324 
329  bool should_stop() const { return should_stop_.load(); }
330 
335  bool check_stop();
336 
342  size_t ev_counter_inc(size_t step = 1); // returns the prev value
343 
348  void set_exception(bool exception) { exception_.store(exception); }
349 
354  void metricsReportingInstanceName(std::string const& name)
355  {
356  instance_name_for_metrics_ = name;
357  }
358 
359  // John F., 12/10/13
360  // Is there a better way to handle mutex_ than leaving it a protected variable?
361 
362  // John F., 1/21/15
363  // Translation above is "should mutex_ be a private variable,
364  // accessible via a getter function". Probably, but at this point
365  // it's not worth breaking code by implementing this.
366 
367  std::mutex mutex_;
368 
373  std::shared_ptr<RequestBuffer> GetRequestBuffer() { return requestBuffer_; }
374 
375  std::shared_ptr<FragmentBuffer> GetFragmentBuffer() { return fragmentBuffer_; }
376 
377 private:
382 
383  // FHiCL-configurable variables. Note that the C++ variable names
384  // are the FHiCL variable names with a "_" appended
385 
386  // Socket parameters
387 
388  std::map<Fragment::fragment_id_t, Fragment::type_t> expectedTypes_;
389 
390  bool useMonitoringThread_;
391  boost::thread monitoringThread_;
392  int64_t monitoringInterval_; // Microseconds
393  std::chrono::steady_clock::time_point lastMonitoringCall_;
394  std::atomic<bool> isHardwareOK_;
395 
396  // In order to support the state-machine related behavior, all
397  // CommandableFragmentGenerators must be able to remember a run number and a
398  // subrun number.
399  int run_number_, subrun_number_;
400 
401  // JCF, 8/28/14
402 
403  // Provide a user-adjustable timeout for the start transition
404  uint64_t timeout_;
405 
406  // JCF, 8/21/14
407 
408  // In response to a need to synchronize various components using
409  // different fragment generators in an experiment, keep a record
410  // of a timestamp (see Redmine Issue #6783 for more)
411 
412  uint64_t timestamp_;
413 
414  std::atomic<bool> should_stop_, exception_;
415  std::string latest_exception_report_;
416  std::atomic<size_t> ev_counter_;
417 
418  std::string instance_name_for_metrics_;
419 
420  // Depending on what sleep_on_stop_us_ is set to, this gives the
421  // stopping thread the chance to gather the required lock
422 
423  int sleep_on_stop_us_;
424 
425  // So that derived classes can access information about requests
426  std::shared_ptr<RequestBuffer> requestBuffer_;
427  std::shared_ptr<FragmentBuffer> fragmentBuffer_;
428 
429 protected:
437  virtual bool getNext_(FragmentPtrs& output) = 0;
438 
445  virtual bool checkHWStatus_();
446 
447  //
448  // State-machine related implementor interface below.
449  //
450 
461  virtual void start() = 0;
462 
469  virtual void stopNoMutex() = 0;
470 
479  virtual void stop() = 0;
480 
485  virtual void pauseNoMutex();
486 
492  virtual void pause();
493 
497  virtual void resume();
498 
510  virtual std::string report();
511 
517  virtual std::string reportSpecific(std::string const& what);
518 };
519 } // namespace artdaq
520 
521 #endif /* artdaq_Application_CommandableFragmentGenerator_hh */
fhicl::Atom< Fragment::type_t > expected_fragment_type
&quot;expected_fragment_type&quot; (Default: 231, EmptyFragmentType) : The type of Fragments this CFG will be g...
CommandableFragmentGenerator(const fhicl::ParameterSet &ps)
CommandableFragmentGenerator Constructor.
int subrun_number() const
Get the current Subrun number.
virtual void start()=0
If a CommandableFragmentGenerator subclass is reading from a file, and start() is called...
fhicl::Atom< int64_t > hardware_poll_interval_us
&quot;hardware_poll_interval_us&quot; (Default: 0) : If a separate monitoring thread is used, how often should it call checkHWStatus_
virtual bool checkHWStatus_()
Check any relavent hardware status registers. Return false if an error condition exists that should h...
virtual ~CommandableFragmentGenerator()
CommandableFragmentGenerator Destructor.
bool exception() const
Get the current value of the exception flag.
void metricsReportingInstanceName(std::string const &name)
Sets the name for metrics reporting.
std::mutex mutex_
Mutex used to ensure that multiple transition commands do not run at the same time.
void getMonitoringDataLoop()
This function regularly calls checkHWStatus_(), and sets the isHardwareOK flag accordingly.
artdaq::Fragment::fragment_id_t fragment_id() const
Get the Fragment ID of this Fragment generator.
std::string ReportCmd(std::string const &which="")
Get a report about a user-specified run-time quantity.
virtual bool metaCommand(std::string const &command, std::string const &arg)
The meta-command is used for implementing user-specific commands in a CommandableFragmentGenerator.
void StopCmd(uint64_t timeout, uint64_t timestamp)
Stop the CommandableFragmentGenerator.
uint64_t timeout() const
Timeout of last command.
void StartCmd(int run, uint64_t timeout, uint64_t timestamp)
Start the CommandableFragmentGenerator.
virtual void pauseNoMutex()
On call to PauseCmd, pauseNoMutex() is called prior to PauseCmd acquiring the mutex ...
bool check_stop()
Routine used by applyRequests to make sure that all outstanding requests have been fulfilled before r...
void ResumeCmd(uint64_t timeout, uint64_t timestamp)
Resume the CommandableFragmentGenerator.
bool getNext(FragmentPtrs &output) overridefinal
getNext calls either applyRequests or getNext_ to get any data that is ready to be sent to the EventB...
std::vector< Fragment::fragment_id_t > fragmentIDs() override
Get the list of Fragment IDs handled by this CommandableFragmentGenerator.
fhicl::Atom< int > sleep_on_stop_us
&quot;sleep_on_stop_us&quot; (Default: 0) : How long to sleep before returning when stop transition is called ...
void PauseCmd(uint64_t timeout, uint64_t timestamp)
Pause the CommandableFragmentGenerator.
fhicl::Sequence< Fragment::fragment_id_t > fragment_ids
virtual std::string metricsReportingInstanceName() const
Get the name used when reporting metrics.
bool should_stop() const
Get the current value of the should_stop flag.
CommandableFragmentGenerator is a FragmentGenerator-derived abstract class that defines the interface...
fhicl::WrappedTable< Config > Parameters
Used for ParameterSet validation (if desired)
virtual bool getNext_(FragmentPtrs &output)=0
Obtain the next group of Fragments, if any are available. Return false if readout cannot continue...
void startMonitoringThread()
Function that launches the monitoring thread (getMonitoringDataLoop())
virtual void pause()
If a CommandableFragmentGenerator subclass is reading from hardware, the implementation of pause() sh...
virtual void resume()
The subrun number will be incremented before a call to resume.
size_t ev_counter() const
Get the current value of the event counter.
fhicl::Atom< size_t > sleep_on_no_data_us
&quot;sleep_on_no_data_us&quot; (Default: 0 (no sleep)) : How long to sleep after calling getNext_ if no data i...
virtual std::string report()
Let&#39;s say that the contract with the report() functions is that they return a non-empty string if the...
virtual void stopNoMutex()=0
On call to StopCmd, stopNoMutex() is called prior to StopCmd acquiring the mutex
std::shared_ptr< RequestBuffer > GetRequestBuffer()
Get the shared_ptr to the RequestBuffer.
void SetRequestBuffer(std::shared_ptr< RequestBuffer > buffer)
Set the shared_ptr to the RequestBuffer.
void set_exception(bool exception)
Control the exception flag.
uint64_t timestamp() const
Timestamp of last command.
Configuration of the CommandableFragmentGenerator. May be used for parameter validation ...
fhicl::Atom< std::string > generator_type
&quot;generator&quot; (REQUIRED) Name of the CommandableFragmentGenerator plugin to load
size_t ev_counter_inc(size_t step=1)
Increment the event counter.
virtual void stop()=0
If a CommandableFragmentGenerator subclass is reading from a file, calling stop() should arrange that...
virtual std::string reportSpecific(std::string const &what)
Report the status of a specific quantity
int run_number() const
Get the current Run number.
fhicl::Atom< bool > separate_monitoring_thread
&quot;separate_monitoring_thread&quot; (Default: false) : Whether a thread that calls the checkHWStatus_ method...
void joinThreads()
Join any data-taking threads. Should be called when destructing CommandableFragmentGenerator.