class CEventFilter : public CEventSink { protected: Bool_t m_fEnabled; std::string m_sFileName; std::vector<std::string> m_vParameterNames; std::vector<UInt_t> m_vParameterIds; CFilterOutputStage* m_pOutput; public: CEventFilter(std::string& rFileName); std::vector<std::string> getParameterNames() const; std::vector<UInt_t> getParameterIds() const; Bool_t CheckEnabled() const; std::string getFileName() const; CFilterOutputStage* getOutputStream(); void setParameterNames(const std::vector<std::string>& names); void setOutputStream(CFilterOutputStage* str); void Enable(); void Disable(); void setFileName(std::string&); void setOutputFormat(CFilterOutputStage* format); std::string outputFormat() const; virtual void operator()(CEventList& rEvents); virtual void operator()(CEvent& rEvent); protected: virtual Bool_t CheckCondition(CEvent& rEvent) = 0; static std::string DefaultFilterFilename(); void NamesToIds(); std::vector<std::string> IdsToNames() };
Filters are objects that, since they are derived from
CEventSink
, can be added to the
event sink pipeline. Filters are expected to operate on
decoded events. They have:
A file to which output data are written
A list of parameters that will be output.
A condition that determines which events are written
A formatting object that determines how the events are written to the output file.
Thus filters create subsets of the raw input data. The output of filters both subset the events (writing only those events that satisfy their condition), and the parameters (writing only the specified parameters).
Filters can speed up subsequent event processing both by reducing the volume of data produced and by writing data in a format much easier to decode than the original raw event data. People using filters have reported over an order of magnitude improvement in the processing of e.g. XDR formatted filtered data over raw data, even when no selection has been performed.
CEventFilter(std::string& rFileName);
Constructor. rFilename
references
the name of the file that filtered data will be written
into. The file is not opened by the constructor.
const std::vector<std::string> getParameterNames();
Returns a vector containing the names of the parameters that will be output by this filter.
const std::vector<UInt_t> getParameterIds();
Returns a vector that contains the ids of the parameters that will be output by the filter.
const Bool_t CheckEnabled();
Returns kfTRUE if the filter is currently enabled else kfFALSE.
const std::string getFileName();
Returns the name of the output file associated with
this filter. At construction time, the default
filter filename is associated with the filter:
$HOME/filter.flt. Normally
thsi is overridden by a call to
setFilename
.
CFilterOutputStage* getOutputStream() getOutputStream();
Returns a pointer to the output stream object associated with this filter. The output stream is responsible for actually opening, and writing filter data to the filter file. If this has not yet been set then nullptr is returned.
void setParameterNames(const std::vector<std::string>& names);
Sets the names of the filter parameters. Note that
this does not populate the parameter id vector
of the filter. To do that, one must first
invoke IdsToNames
.
This functional separation is done to allow the filter
to account for changes in parameter definitions between
selecting which parameters to output and actually
applying the filter.
void setOutputStream(CFilterOutputStage* str);
Sets the output stage for the filter. The output
stage is what is actually responsible for connecting
to the filter file and outputting data to it.
Note that this is an alias for and delegates to
setOutputFormat
.
void Enable();
,
void Disable();
Enable or disable the filter respectively. Only enabled filters will check and output data. Disabled filters do nothing.
void setFileName(std::string& filename);
Sets a new filename for the filter. It's up to the filter output stage to understand what to do with this filename. When the filter is enabled, the output stage will be asked to open the current filename and to describe the parameter names and ids to the filter file.
void setOutputFormat(CFilterOutputStage* format);
Sets the new CFilterOutpuStage
object associated with the filter to
format
. Note that if
the filter is enabled, this method throws a
CStateException
because
it's not legal to switch format types in the middle
of filtering the data.
const std::string outputFormat();
Asks the current output stream to return a description of itself. If there is no current output stream the string -- is returned to indicate the filter output format has not been selected. Note that SpecTcl's command interface to filters will never create a filter that does not have an output format defined.
virtual void operator()(CEventList& rEvents);
Asks the filter to process the events
rEvents
. If the filters is
not enabled, this method does nothing. If it is,
then for each item in rEvents
the
overload for operator()
described
below is invoked for that item.
virtual void operator()(CEvent& rEvent);
The filter is processed for the single event
rEvent
. The pure virtual method
CheckCondition
is invoked.
If that returns kfTRUE, the
output stream is handed the event and directed to
output it in its format to the filter output file.
protected virtual = 0 Bool_t CheckCondition(CEvent& rEvent);
This pure virtual method must be implemented by
concrete filter classes. It provides a predicate that
is called for every event passed to an enabled filter to
determine if the event should be output. For example,
for the CGateEventFilter
class,
the implementation of this method evaluates the gate
associated with that filter.
protected static std::string DefaultFilterFilename();
Returns the full default path of the filter output file. It is strongly recommended that this file not be used as you could imagine the chaos that would result if multiple instances of the filter used the default output file.
The method returns $HOME/filter.flt where, $HOME is the translation of the HOME environment variable. At login, this variable is set to the user's home directory path. Note that there's no guarantee it points there at the time this method is called.
protected void NamesToIds();
Populates the parameter id vector held internally from the parameter names vector. Each parameter name is looked up in the parameter dictionary. If a name has a matching parameter definition, it's id is added to the array. Any parameters that do not have a definition are silently omitted from the array.
protected std::vector<std::string> IdsToNames();
Given the object's vector of parameter ids, returns
a vector containing the names of all parameters
in corresponding positions of that vector. If
a parameter does not exist in the dictionary any more,
a CDictictionaryException
is thrown.
Note that a call to NamesToIds
followed by a call to this method returns the filter
parameter names with nonexistent parameters removed.
Several data members are protected and hence available to subclasses directly. Subclasses can also use the getters and setters for these members rather than accessing them directly.
m_fEnabled
Enable flag for the filter kfTRUE
if the filter is enabled or kfFALSE
if not. This is the value returned by
CheckEnabled
.
m_sFileName
Name of the file associated withthe filter. This
is the value returned by
getFileName
.
m_vParameterNames
Vector of the names of the parameters to be output
to the filter file for events that should be written.
This is the value returned by
getParameterNames
.
m_vParameterIds
Vector of parameter ids produced by
NamesToIdes
. This is
the value returned by
getParameterIds
.
m_pOutput;
Pointer to the output stream used by the filter
to write events. This is the value returned by
getOutputStream