artdaq
v3_00_01
|
CommandableFragmentGenerator is a FragmentGenerator-derived abstract class that defines the interface for a FragmentGenerator designed as a state machine with start, stop, etc., transition commands. More...
#include <artdaq/Application/CommandableFragmentGenerator.hh>
Public Member Functions | |
CommandableFragmentGenerator () | |
CommandableFragmentGenerator default constructor. More... | |
CommandableFragmentGenerator (const fhicl::ParameterSet &ps) | |
CommandableFragmentGenerator Constructor. More... | |
virtual | ~CommandableFragmentGenerator () |
CommandableFragmentGenerator Destructor. More... | |
void | joinThreads () |
Join any data-taking threads. Should be called when destructing CommandableFragmentGenerator. More... | |
bool | getNext (FragmentPtrs &output) overridefinal |
getNext calls either applyRequests or getNext_ to get any data that is ready to be sent to the EventBuilders More... | |
void | applyRequestsIgnoredMode (artdaq::FragmentPtrs &frags) |
Create fragments using data buffer for request mode Ignored. Precondition: dataBufferMutex_ and request_mutex_ are locked More... | |
void | applyRequestsSingleMode (artdaq::FragmentPtrs &frags) |
Create fragments using data buffer for request mode Single. Precondition: dataBufferMutex_ and request_mutex_ are locked More... | |
void | applyRequestsBufferMode (artdaq::FragmentPtrs &frags) |
Create fragments using data buffer for request mode Buffer. Precondition: dataBufferMutex_ and request_mutex_ are locked More... | |
void | applyRequestsWindowMode (artdaq::FragmentPtrs &frags) |
Create fragments using data buffer for request mode Window. Precondition: dataBufferMutex_ and request_mutex_ are locked More... | |
bool | applyRequests (FragmentPtrs &output) |
See if any requests have been received, and add the corresponding data Fragment objects to the output list. More... | |
void | setupRequestListener () |
Opens the socket used to listen for data requests. | |
bool | sendEmptyFragment (FragmentPtrs &frags, size_t sequenceId, std::string desc) |
Send an EmptyFragmentType Fragment. More... | |
void | sendEmptyFragments (FragmentPtrs &frags) |
This function is for Buffered and Single request modes, as they can only respond to one data request at a time If the request message seqID > ev_counter, simply send empties until they're equal. More... | |
void | startDataThread () |
Function that launches the data thread (getDataLoop()) | |
void | startMonitoringThread () |
Function that launches the monitoring thread (getMonitoringDataLoop()) | |
void | startRequestReceiverThread () |
Function that launches the data request receiver thread (receiveRequestsLoop()) | |
void | getDataLoop () |
When separate_data_thread is set to true, this loop repeatedly calls getNext_ and adds returned Fragment objects to the data buffer, blocking when the data buffer is full. | |
bool | waitForDataBufferReady () |
Wait for the data buffer to drain (dataBufferIsTooLarge returns false), periodically reporting status. More... | |
bool | dataBufferIsTooLarge () |
Test the configured constraints on the data buffer. More... | |
void | getDataBufferStats () |
Calculate the size of the dataBuffer and report appropriate metrics. More... | |
void | checkDataBuffer () |
Perform data buffer pruning operations. If the RequestMode is Single, removes all but the latest Fragment from the data buffer. In Window and Buffer RequestModes, this function discards the oldest Fragment objects until the data buffer is below its size constraints, then also checks for stale Fragments, based on the timestamp of the most recent Fragment. | |
void | getMonitoringDataLoop () |
This function regularly calls checkHWStatus_(), and sets the isHardwareOK flag accordingly. | |
void | receiveRequestsLoop () |
This function receives data request packets, adding new requests to the request list. | |
std::vector < Fragment::fragment_id_t > | fragmentIDs () override |
Get the list of Fragment IDs handled by this CommandableFragmentGenerator. More... | |
void | StartCmd (int run, uint64_t timeout, uint64_t timestamp) |
Start the CommandableFragmentGenerator. More... | |
void | StopCmd (uint64_t timeout, uint64_t timestamp) |
Stop the CommandableFragmentGenerator. More... | |
void | PauseCmd (uint64_t timeout, uint64_t timestamp) |
Pause the CommandableFragmentGenerator. More... | |
void | ResumeCmd (uint64_t timeout, uint64_t timestamp) |
Resume the CommandableFragmentGenerator. More... | |
std::string | ReportCmd (std::string const &which="") |
Get a report about a user-specified run-time quantity. More... | |
virtual std::string | metricsReportingInstanceName () const |
Get the name used when reporting metrics. More... | |
bool | exception () const |
Get the current value of the exception flag. More... | |
Protected Member Functions | |
int | run_number () const |
Get the current Run number. More... | |
int | subrun_number () const |
Get the current Subrun number. More... | |
uint64_t | timeout () const |
Timeout of last command. More... | |
uint64_t | timestamp () const |
Timestamp of last command. More... | |
bool | should_stop () const |
Get the current value of the should_stop flag. More... | |
bool | check_stop () |
Routine used by applyRequests to make sure that all outstanding requests have been fulfilled before returning. More... | |
int | board_id () const |
Gets the current board_id. More... | |
int | fragment_id () const |
Get the current Fragment ID, if there is only one. More... | |
size_t | ev_counter () const |
Get the current value of the event counter. More... | |
size_t | ev_counter_inc (size_t step=1, bool force=false) |
Increment the event counter, if the current RequestMode allows it. More... | |
void | set_exception (bool exception) |
Control the exception flag. More... | |
void | metricsReportingInstanceName (std::string const &name) |
Sets the name for metrics reporting. More... | |
std::string | printMode_ () |
Return the string representation of the current RequestMode. More... | |
virtual bool | getNext_ (FragmentPtrs &output)=0 |
virtual bool | checkHWStatus_ () |
virtual void | start ()=0 |
virtual void | stopNoMutex ()=0 |
virtual void | stop ()=0 |
virtual void | pauseNoMutex () |
virtual void | pause () |
virtual void | resume () |
virtual std::string | report () |
virtual std::string | reportSpecific (std::string const &) |
Protected Attributes | |
std::mutex | mutex_ |
Mutex used to ensure that multiple transition commands do not run at the same time. | |
CommandableFragmentGenerator is a FragmentGenerator-derived abstract class that defines the interface for a FragmentGenerator designed as a state machine with start, stop, etc., transition commands.
Users of classes derived from CommandableFragmentGenerator will call these transitions via the publically defined StartCmd(), StopCmd(), etc.; these public functions contain functionality considered properly universal to all CommandableFragmentGenerator-derived classes, including calls to private virtual functions meant to be overridden in derived classes. The same applies to this class's implementation of the FragmentGenerator::getNext() pure virtual function, which is declared final (i.e., non-overridable in derived classes) and which itself calls a pure virtual getNext_() function to be implemented in derived classes.
State-machine related interface functions will be called only from a single thread. getNext() will be called only from a single thread. The thread from which state-machine interfaces functions are called may be a different thread from the one that calls getNext().
John F., 3/24/14
After some discussion with Kurt, CommandableFragmentGenerator has been updated such that it now contains a member vector fragment_ids_ ; if "fragment_id" is set in the FHiCL document controlling a class derived from CommandableFragmentGenerator, fragment_ids_ will be booked as a length-1 vector, and the value in this vector will be returned by fragment_id(). fragment_id() will throw an exception if the length of the vector isn't 1. If "fragment_ids" is set in the FHiCL document, then fragment_ids_ is filled with the values in the list which "fragment_ids" refers to, otherwise it is set to the empty vector (this is what should happen if the user sets the "fragment_id" variable in the FHiCL document, otherwise exceptions will end up thrown due to the logical conflict). If neither "fragment_id" nor "fragment_ids" is set in the FHiCL document, writers of classes derived from this one will be expected to override the virtual fragmentIDs() function with their own code (the CompositeDriver class is an example of this)
Definition at line 82 of file CommandableFragmentGenerator.hh.
artdaq::CommandableFragmentGenerator::CommandableFragmentGenerator | ( | ) |
CommandableFragmentGenerator default constructor.
This constructor defalt-initializes all parameters
Definition at line 31 of file CommandableFragmentGenerator.cc.
|
explicit |
CommandableFragmentGenerator Constructor.
ps | ParameterSet used to configure CommandableFragmentGenerator |
* CommandableFragmentGenerator accepts the following Parameters: * "request_port" (Default: 3001): Port on which data requests will be received * "request_address" (Default: "227.128.12.26"): Address which CommandableFragmentGenerator will listen for requests on * "end_of_run_quiet_timeout_ms" (Default: 1000): Time, in milliseconds, that the entire system must be quiet for check_stop to return true in request mode. **DO NOT EDIT UNLESS YOU KNOW WHAT YOU ARE DOING!** * "request_window_offset" (Default: 0): Request messages contain a timestamp. For Window request mode, start the window this far before the timestamp in the request * "request_window_width" (Default: 0): For Window request mode, the window will be timestamp - offset to timestamp - offset + width * "stale_request_timeout" (Default: -1): How long should request messages be retained * "request_windows_are_unique" (Default: true): Whether Fragments should be removed from the buffer when matched to a request window * "missing_request_window_timeout_us" (Default: 1s): How long to wait for a missing request in Window mode (measured from the last time data was sent) * "window_close_timeout_us" (Default: 2s): How long to wait for the end of the data buffer to pass the end of a request window (measured from the last time data was sent) * "expected_fragment_type" (Default: 231, EmptyFragmentType): The type of Fragments this CFG will be generating. "Empty" will auto-detect type based on Fragments generated. * "separate_data_thread" (Default: false): Whether data collection should proceed on its own thread. Required for all data request processing * "sleep_on_no_data_us" (Default: 0 (no sleep)): How long to sleep after calling getNext_ if no data is returned * "data_buffer_depth_fragments" (Default: 1000): How many Fragments to store in the buffer * "data_buffer_depth_mb" (Default: 1000): The maximum size of the data buffer in MB * "separate_monitoring_thread" (Default: false): Whether a thread that calls the checkHWStatus_ method should be created * "hardware_poll_interval_us" (Default: 0): If a separate monitoring thread is used, how often should it call checkHWStatus_ * "board_id" (REQUIRED): The identification number for this CommandableFragmentGenerator * "fragment_ids" (Default: empty vector): A list of Fragment IDs created by this CommandableFragmentGenerator * "fragment_id" (Default: -99): The Fragment ID created by this CommandableFragmentGenerator * Note that only one of fragment_ids and fragment_id should be specified in the configuration * "sleep_on_stop_us" (Default: 0): How long to sleep before returning when stop transition is called * "request_mode" (Deafult: Ignored): The mode by which the CommandableFragmentGenerator will process reqeusts * Ignored: Request messages are ignored. This is a "push" CommandableFragmentGenerator * Single: The CommandableFragmentGenerator responds to each request with the latest Fragment it has received * Buffer: The CommandableFragmentGenerator responds to each request with all Fragments it has received since the last request * Window: The CommandableFragmentGenerator searches its data buffer for all Fragments whose timestamp falls within the request window *
Definition at line 78 of file CommandableFragmentGenerator.cc.
|
virtual |
CommandableFragmentGenerator Destructor.
Joins all threads before returning
Definition at line 226 of file CommandableFragmentGenerator.cc.
bool artdaq::CommandableFragmentGenerator::applyRequests | ( | FragmentPtrs & | output | ) |
See if any requests have been received, and add the corresponding data Fragment objects to the output list.
[out] | output | list of FragmentPtr objects ready for transmission |
Definition at line 1025 of file CommandableFragmentGenerator.cc.
void artdaq::CommandableFragmentGenerator::applyRequestsBufferMode | ( | artdaq::FragmentPtrs & | frags | ) |
Create fragments using data buffer for request mode Buffer. Precondition: dataBufferMutex_ and request_mutex_ are locked
frags | Ouput fragments |
Definition at line 883 of file CommandableFragmentGenerator.cc.
void artdaq::CommandableFragmentGenerator::applyRequestsIgnoredMode | ( | artdaq::FragmentPtrs & | frags | ) |
Create fragments using data buffer for request mode Ignored. Precondition: dataBufferMutex_ and request_mutex_ are locked
frags | Ouput fragments |
Definition at line 844 of file CommandableFragmentGenerator.cc.
void artdaq::CommandableFragmentGenerator::applyRequestsSingleMode | ( | artdaq::FragmentPtrs & | frags | ) |
Create fragments using data buffer for request mode Single. Precondition: dataBufferMutex_ and request_mutex_ are locked
frags | Ouput fragments |
Definition at line 852 of file CommandableFragmentGenerator.cc.
void artdaq::CommandableFragmentGenerator::applyRequestsWindowMode | ( | artdaq::FragmentPtrs & | frags | ) |
Create fragments using data buffer for request mode Window. Precondition: dataBufferMutex_ and request_mutex_ are locked
frags | Ouput fragments |
Definition at line 908 of file CommandableFragmentGenerator.cc.
|
inlineprotected |
Gets the current board_id.
Definition at line 415 of file CommandableFragmentGenerator.hh.
|
protected |
Routine used by applyRequests to make sure that all outstanding requests have been fulfilled before returning.
Definition at line 338 of file CommandableFragmentGenerator.cc.
bool artdaq::CommandableFragmentGenerator::dataBufferIsTooLarge | ( | ) |
Test the configured constraints on the data buffer.
Definition at line 671 of file CommandableFragmentGenerator.cc.
|
inlineprotected |
Get the current value of the event counter.
Definition at line 428 of file CommandableFragmentGenerator.hh.
|
protected |
Increment the event counter, if the current RequestMode allows it.
step | Amount to increment the event counter by |
force | Force incrementing the event Counter |
Definition at line 370 of file CommandableFragmentGenerator.cc.
|
inline |
Get the current value of the exception flag.
Definition at line 366 of file CommandableFragmentGenerator.hh.
|
protected |
Get the current Fragment ID, if there is only one.
cet::exception | if the Fragment IDs list has more than one member |
Definition at line 358 of file CommandableFragmentGenerator.cc.
|
inlineoverride |
Get the list of Fragment IDs handled by this CommandableFragmentGenerator.
Definition at line 268 of file CommandableFragmentGenerator.hh.
void artdaq::CommandableFragmentGenerator::getDataBufferStats | ( | ) |
Calculate the size of the dataBuffer and report appropriate metrics.
dataBufferMutex must be owned by the calling thread!
Definition at line 676 of file CommandableFragmentGenerator.cc.
|
finaloverride |
getNext calls either applyRequests or getNext_ to get any data that is ready to be sent to the EventBuilders
output | FragmentPtrs object containing Fragments ready for transmission |
Definition at line 244 of file CommandableFragmentGenerator.cc.
void artdaq::CommandableFragmentGenerator::joinThreads | ( | ) |
Join any data-taking threads. Should be called when destructing CommandableFragmentGenerator.
Join any data-taking threads. Should be called when destructing CommandableFragmentGenerator Sets flags so that threads stop operations.
Definition at line 231 of file CommandableFragmentGenerator.cc.
|
inlinevirtual |
Get the name used when reporting metrics.
Definition at line 341 of file CommandableFragmentGenerator.hh.
|
inlineprotected |
Sets the name for metrics reporting.
name | The new name for metrics reporting |
Definition at line 448 of file CommandableFragmentGenerator.hh.
void artdaq::CommandableFragmentGenerator::PauseCmd | ( | uint64_t | timeout, |
uint64_t | timestamp | ||
) |
Pause the CommandableFragmentGenerator.
timeout | Timeout for transition |
timestamp | Timestamp of transition |
A call to PauseCmd() is advisory. It is an indication that the BoardReader should stop the incoming flow of data, if it can do so.
Definition at line 416 of file CommandableFragmentGenerator.cc.
|
protected |
Return the string representation of the current RequestMode.
Definition at line 533 of file CommandableFragmentGenerator.cc.
std::string artdaq::CommandableFragmentGenerator::ReportCmd | ( | std::string const & | which = "" | ) |
Get a report about a user-specified run-time quantity.
which | Which quantity to report |
CommandableFragmentGenerator only implements "latest_exception", a report on the last exception received. However, child classes can override the reportSpecific function to provide additional reports.
Definition at line 448 of file CommandableFragmentGenerator.cc.
void artdaq::CommandableFragmentGenerator::ResumeCmd | ( | uint64_t | timeout, |
uint64_t | timestamp | ||
) |
Resume the CommandableFragmentGenerator.
timeout | Timeout for transition |
timestamp | Timestamp of transition |
After a call to ResumeCmd(), the next Fragments returned from getNext() will be part of a new SubRun.
Definition at line 428 of file CommandableFragmentGenerator.cc.
|
inlineprotected |
Get the current Run number.
Definition at line 382 of file CommandableFragmentGenerator.hh.
bool artdaq::CommandableFragmentGenerator::sendEmptyFragment | ( | FragmentPtrs & | frags, |
size_t | sequenceId, | ||
std::string | desc | ||
) |
Send an EmptyFragmentType Fragment.
[out] | frags | Output list to append EmptyFragmentType to |
sequenceId | Sequence ID of Empty Fragment | |
desc | Message to log with reasoning for sending Empty Fragment |
Definition at line 1087 of file CommandableFragmentGenerator.cc.
void artdaq::CommandableFragmentGenerator::sendEmptyFragments | ( | FragmentPtrs & | frags | ) |
This function is for Buffered and Single request modes, as they can only respond to one data request at a time If the request message seqID > ev_counter, simply send empties until they're equal.
[out] | frags | Output list to append EmptyFragmentType to |
Definition at line 1101 of file CommandableFragmentGenerator.cc.
|
inlineprotected |
Control the exception flag.
exception | Whether an excpetion has occurred |
Definition at line 442 of file CommandableFragmentGenerator.hh.
|
inlineprotected |
Get the current value of the should_stop flag.
Definition at line 403 of file CommandableFragmentGenerator.hh.
void artdaq::CommandableFragmentGenerator::StartCmd | ( | int | run, |
uint64_t | timeout, | ||
uint64_t | timestamp | ||
) |
Start the CommandableFragmentGenerator.
run | Run ID of the new run |
timeout | Timeout for transition |
timestamp | Timestamp of transition |
After a call to 'StartCmd', all Fragments returned by getNext() will be marked as part of a Run with the given run number, and with subrun number 1. Calling StartCmd also resets the event number to 1. After a call to StartCmd(), and until a call to StopCmd, getNext() – and hence the virtual function it calls, getNext_() – should return true as long as datataking is meant to take place, even if a particular call returns no fragments.
Definition at line 379 of file CommandableFragmentGenerator.cc.
void artdaq::CommandableFragmentGenerator::StopCmd | ( | uint64_t | timeout, |
uint64_t | timestamp | ||
) |
Stop the CommandableFragmentGenerator.
timeout | Timeout for transition |
timestamp | Timestamp of transition |
After a call to StopCmd(), getNext() will eventually return false. This may not happen for several calls, if the implementation has data to be 'drained' from the system.
Definition at line 403 of file CommandableFragmentGenerator.cc.
|
inlineprotected |
Get the current Subrun number.
Definition at line 387 of file CommandableFragmentGenerator.hh.
|
inlineprotected |
Timeout of last command.
Definition at line 392 of file CommandableFragmentGenerator.hh.
|
inlineprotected |
Timestamp of last command.
Definition at line 397 of file CommandableFragmentGenerator.hh.
bool artdaq::CommandableFragmentGenerator::waitForDataBufferReady | ( | ) |
Wait for the data buffer to drain (dataBufferIsTooLarge returns false), periodically reporting status.
Definition at line 638 of file CommandableFragmentGenerator.cc.