artdaq  v3_00_03
artdaq::CommandableFragmentGenerator Class Referenceabstract

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>

Inheritance diagram for artdaq::CommandableFragmentGenerator:
artdaq::CompositeDriver artdaqtest::CommandableFragmentGeneratorTest

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...
 
bool sendEmptyFragment (FragmentPtrs &frags, size_t sequenceId, std::string desc)
 Send an EmptyFragmentType Fragment. More...
 
void sendEmptyFragments (FragmentPtrs &frags, std::map< Fragment::sequence_id_t, Fragment::timestamp_t > &requests)
 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 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.
 
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...
 
virtual bool metaCommand (std::string const &command, std::string const &arg)
 The meta-command is used for implementing user-specific commands in a CommandableFragmentGenerator. 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.
 

Detailed Description

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 83 of file CommandableFragmentGenerator.hh.

Constructor & Destructor Documentation

artdaq::CommandableFragmentGenerator::CommandableFragmentGenerator ( )

CommandableFragmentGenerator default constructor.

This constructor defalt-initializes all parameters

Definition at line 31 of file CommandableFragmentGenerator.cc.

artdaq::CommandableFragmentGenerator::CommandableFragmentGenerator ( const fhicl::ParameterSet &  ps)
explicit

CommandableFragmentGenerator Constructor.

Parameters
psParameterSet 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 74 of file CommandableFragmentGenerator.cc.

artdaq::CommandableFragmentGenerator::~CommandableFragmentGenerator ( )
virtual

CommandableFragmentGenerator Destructor.

Joins all threads before returning

Definition at line 169 of file CommandableFragmentGenerator.cc.

Member Function Documentation

bool artdaq::CommandableFragmentGenerator::applyRequests ( FragmentPtrs &  output)

See if any requests have been received, and add the corresponding data Fragment objects to the output list.

Parameters
[out]outputlist of FragmentPtr objects ready for transmission
Returns
True if not stopped

Definition at line 912 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

Parameters
fragsOuput fragments

Definition at line 747 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

Parameters
fragsOuput fragments

Definition at line 702 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

Parameters
fragsOuput fragments

Definition at line 710 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

Parameters
fragsOuput fragments

Definition at line 779 of file CommandableFragmentGenerator.cc.

int artdaq::CommandableFragmentGenerator::board_id ( ) const
inlineprotected

Gets the current board_id.

Returns
The current board_id

Definition at line 411 of file CommandableFragmentGenerator.hh.

bool artdaq::CommandableFragmentGenerator::check_stop ( )
protected

Routine used by applyRequests to make sure that all outstanding requests have been fulfilled before returning.

Returns
The logical AND of should_stop, mode is not Ignored, and requests list size equal to 0

Definition at line 279 of file CommandableFragmentGenerator.cc.

bool artdaq::CommandableFragmentGenerator::dataBufferIsTooLarge ( )

Test the configured constraints on the data buffer.

Returns
Whether the data buffer is full

Definition at line 605 of file CommandableFragmentGenerator.cc.

size_t artdaq::CommandableFragmentGenerator::ev_counter ( ) const
inlineprotected

Get the current value of the event counter.

Returns
The current value of the event counter

Definition at line 424 of file CommandableFragmentGenerator.hh.

size_t artdaq::CommandableFragmentGenerator::ev_counter_inc ( size_t  step = 1,
bool  force = false 
)
protected

Increment the event counter, if the current RequestMode allows it.

Parameters
stepAmount to increment the event counter by
forceForce incrementing the event Counter
Returns
The previous value of the event counter

Definition at line 303 of file CommandableFragmentGenerator.cc.

bool artdaq::CommandableFragmentGenerator::exception ( ) const
inline

Get the current value of the exception flag.

Returns
The current value of the exception flag

Definition at line 353 of file CommandableFragmentGenerator.hh.

int artdaq::CommandableFragmentGenerator::fragment_id ( ) const
protected

Get the current Fragment ID, if there is only one.

Returns
The current fragment ID, if the re is only one
Exceptions
cet::exceptionif the Fragment IDs list has more than one member

Definition at line 291 of file CommandableFragmentGenerator.cc.

std::vector<Fragment::fragment_id_t> artdaq::CommandableFragmentGenerator::fragmentIDs ( )
inlineoverride

Get the list of Fragment IDs handled by this CommandableFragmentGenerator.

Returns
A std::vector<Fragment::fragment_id_t> containing the Fragment IDs handled by this CommandableFragmentGenerator

Definition at line 255 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 610 of file CommandableFragmentGenerator.cc.

bool artdaq::CommandableFragmentGenerator::getNext ( FragmentPtrs &  output)
finaloverride

getNext calls either applyRequests or getNext_ to get any data that is ready to be sent to the EventBuilders

Parameters
outputFragmentPtrs object containing Fragments ready for transmission
Returns
Whether getNext completed without exceptions

Definition at line 185 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 174 of file CommandableFragmentGenerator.cc.

bool artdaq::CommandableFragmentGenerator::metaCommand ( std::string const &  command,
std::string const &  arg 
)
virtual

The meta-command is used for implementing user-specific commands in a CommandableFragmentGenerator.

Parameters
commandName of the command to run
argArgument(s) for command
Returns
true if command succeeded or if command not supported

Definition at line 443 of file CommandableFragmentGenerator.cc.

virtual std::string artdaq::CommandableFragmentGenerator::metricsReportingInstanceName ( ) const
inlinevirtual

Get the name used when reporting metrics.

Returns
The name used when reporting metrics

Definition at line 328 of file CommandableFragmentGenerator.hh.

void artdaq::CommandableFragmentGenerator::metricsReportingInstanceName ( std::string const &  name)
inlineprotected

Sets the name for metrics reporting.

Parameters
nameThe new name for metrics reporting

Definition at line 444 of file CommandableFragmentGenerator.hh.

void artdaq::CommandableFragmentGenerator::PauseCmd ( uint64_t  timeout,
uint64_t  timestamp 
)

Pause the CommandableFragmentGenerator.

Parameters
timeoutTimeout for transition
timestampTimestamp 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 348 of file CommandableFragmentGenerator.cc.

std::string artdaq::CommandableFragmentGenerator::printMode_ ( )
protected

Return the string representation of the current RequestMode.

Returns
The string representation of the current RequestMode

Definition at line 463 of file CommandableFragmentGenerator.cc.

std::string artdaq::CommandableFragmentGenerator::ReportCmd ( std::string const &  which = "")

Get a report about a user-specified run-time quantity.

Parameters
whichWhich quantity to report
Returns
The report about the specified quantity

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 379 of file CommandableFragmentGenerator.cc.

void artdaq::CommandableFragmentGenerator::ResumeCmd ( uint64_t  timeout,
uint64_t  timestamp 
)

Resume the CommandableFragmentGenerator.

Parameters
timeoutTimeout for transition
timestampTimestamp of transition

After a call to ResumeCmd(), the next Fragments returned from getNext() will be part of a new SubRun.

Definition at line 360 of file CommandableFragmentGenerator.cc.

int artdaq::CommandableFragmentGenerator::run_number ( ) const
inlineprotected

Get the current Run number.

Returns
The current Run number

Definition at line 378 of file CommandableFragmentGenerator.hh.

bool artdaq::CommandableFragmentGenerator::sendEmptyFragment ( FragmentPtrs &  frags,
size_t  sequenceId,
std::string  desc 
)

Send an EmptyFragmentType Fragment.

Parameters
[out]fragsOutput list to append EmptyFragmentType to
sequenceIdSequence ID of Empty Fragment
descMessage to log with reasoning for sending Empty Fragment
Returns
True if no exceptions

Definition at line 976 of file CommandableFragmentGenerator.cc.

void artdaq::CommandableFragmentGenerator::sendEmptyFragments ( FragmentPtrs &  frags,
std::map< Fragment::sequence_id_t, Fragment::timestamp_t > &  requests 
)

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.

Parameters
[out]fragsOutput list to append EmptyFragmentType to
requestsList of requests to process

Definition at line 990 of file CommandableFragmentGenerator.cc.

void artdaq::CommandableFragmentGenerator::set_exception ( bool  exception)
inlineprotected

Control the exception flag.

Parameters
exceptionWhether an excpetion has occurred

Definition at line 438 of file CommandableFragmentGenerator.hh.

bool artdaq::CommandableFragmentGenerator::should_stop ( ) const
inlineprotected

Get the current value of the should_stop flag.

Returns
The current value of the should_stop flag

Definition at line 399 of file CommandableFragmentGenerator.hh.

void artdaq::CommandableFragmentGenerator::StartCmd ( int  run,
uint64_t  timeout,
uint64_t  timestamp 
)

Start the CommandableFragmentGenerator.

Parameters
runRun ID of the new run
timeoutTimeout for transition
timestampTimestamp 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 312 of file CommandableFragmentGenerator.cc.

void artdaq::CommandableFragmentGenerator::StopCmd ( uint64_t  timeout,
uint64_t  timestamp 
)

Stop the CommandableFragmentGenerator.

Parameters
timeoutTimeout for transition
timestampTimestamp 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 335 of file CommandableFragmentGenerator.cc.

int artdaq::CommandableFragmentGenerator::subrun_number ( ) const
inlineprotected

Get the current Subrun number.

Returns
The current Subrun number

Definition at line 383 of file CommandableFragmentGenerator.hh.

uint64_t artdaq::CommandableFragmentGenerator::timeout ( ) const
inlineprotected

Timeout of last command.

Returns
Timeout of last command

Definition at line 388 of file CommandableFragmentGenerator.hh.

uint64_t artdaq::CommandableFragmentGenerator::timestamp ( ) const
inlineprotected

Timestamp of last command.

Returns
Timestamp of last command

Definition at line 393 of file CommandableFragmentGenerator.hh.

bool artdaq::CommandableFragmentGenerator::waitForDataBufferReady ( )

Wait for the data buffer to drain (dataBufferIsTooLarge returns false), periodically reporting status.

Returns
True if wait ended without something else disrupting the run

Definition at line 568 of file CommandableFragmentGenerator.cc.


The documentation for this class was generated from the following files: