code documentation; minor enhancement of BlockFilter
[u/mrichter/AliRoot.git] / HLT / BASE / util / AliHLTBlockFilterComponent.h
1 // -*- Mode: C++ -*-
2 // @(#) $Id$
3
4 #ifndef ALIHLTBLOCKFILTERCOMPONENT_H
5 #define ALIHLTBLOCKFILTERCOMPONENT_H
6 //* This file is property of and copyright by the ALICE HLT Project        * 
7 //* ALICE Experiment at CERN, All rights reserved.                         *
8 //* See cxx source for full Copyright notice                               *
9
10 /** @file   AliHLTBlockFilterComponent.h
11     @author Matthias Richter
12     @date   
13     @brief  A simple data block filter and merger, merges block descriptors
14 */
15
16 #include "AliHLTProcessor.h"
17
18 /**
19  * @class AliHLTBlockFilterComponent
20  * A data block merger and filter.
21  * It merges data block descriptors fulfilling the filtering rules and
22  * forwards the descriptors to the output. The actual data is not touched.
23  *
24  * <h2>General properties:</h2>
25  *
26  * Component ID: \b BlockFilter                                         <br>
27  * Library: \b libAliHLTUtil.so                                         <br>
28  * Input Data Types: kAliHLTAnyDataType                                 <br>
29  * Output Data Types: according to parameter and input blocks           <br>
30  *
31  * <h2>Mandatory arguments:</h2>
32  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
33  *      
34  * <h2>Optional arguments:</h2>
35  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
36  * \li -datatype     <i> id origin      </i>                            <br>
37  *      e.g. <tt> -datatype 'ESD_TREE' 'TPC ' </tt>                     <br>
38  *      \b Note: due to the 4-character data origin it might be necessary to
39  *      append a blank to the detectorname, e.g. <tt>TPC -> 'TPC '</tt>
40  *
41  * \li -origin  <i> origin  </i>                                        <br>
42  *      e.g. -origin 'TPC ', \b Note:  the filter rule has type id 'ANY'
43  *
44  * \li -typeid  <i> id      </i>                                        <br>
45  *      e.g. -typeid ESD_TREE, \b Note: the filter rule has origin 'ANY'
46  *
47  * \li -dataspec     <i> specification </i>                             <br>
48  *      data specification treated as decimal number or hex number if
49  *      prepended by '0x'
50  *
51  * \li -verbose                                                         <br>
52  *      print out some more info messages, mainly for the sake of tutorials
53  *
54  * <h2>Configuration:</h2>
55  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
56  * Configuration by component arguments.
57  *
58  * <h2>Default CDB entries:</h2>
59  * The component loads no CDB entries.
60  *
61  * <h2>Performance:</h2>
62  * The component does not process any event data.
63  *
64  * <h2>Memory consumption:</h2>
65  * The component does not process any event data.
66  *
67  * <h2>Output size:</h2>
68  * No additional data is produced. Data blocks are just forwarded.
69  *
70  * By default, all blocks will be published. By means of the \em -datatype,
71  * \em -origin, and \em -typeid arguments, the blocks can be selected. A list
72  * of filter rules can be built up by multiple usage of the arguments. Each
73  * time a new filter rule is added.
74  *
75  * No filtering by the data specification is applied unless then \em
76  * -specification argument is used. The specification applies to to the
77  * current filter rule, regardless of the sequence of -datatype/-specification
78  * arguments.
79  *
80  * @ingroup alihlt_util_components
81  */
82 class AliHLTBlockFilterComponent : public AliHLTProcessor
83 {
84  public:
85   /** standard constructor */
86   AliHLTBlockFilterComponent();
87   /** destructor */
88   virtual ~AliHLTBlockFilterComponent();
89
90   /**
91    * The id of the component.
92    * @return component id (string)
93    */
94   virtual const char* GetComponentID() {return "BlockFilter";};
95
96   /**
97    * Get the input data types of the component.
98    * @return list of data types in the vector reference
99    */
100   void GetInputDataTypes( AliHLTComponentDataTypeList& );
101
102   /**
103    * Get the output data type of the component.
104    * If @ref kAliHLTMultipleDataType is returned, the framework invokes
105    * @ref GetOutputDataTypes.
106    * @return output data type
107    */
108   AliHLTComponentDataType GetOutputDataType();
109
110   /**
111    * Get the output data types of the component.
112    * The function can be implemented to indicate multiple output data types
113    * in the target array.
114    * @ref GetOutputDataType must return @ref kAliHLTMultipleDataType in order
115    * to invoke this method.
116    * @param tgtList          list to receive the data types
117    * @return no of output data types, data types in the target list
118    */
119   int GetOutputDataTypes(AliHLTComponentDataTypeList& tgtList);
120
121   /**
122    * Get a ratio by how much the data volume is shrinked or enhanced.
123    * @param constBase        <i>return</i>: additive part, independent of the
124    *                                   input data volume  
125    * @param inputMultiplier  <i>return</i>: multiplication ratio
126    * @return values in the reference variables
127    */
128   void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier );
129
130   /**
131    * Spawn function.
132    * @return new class instance
133    */
134   virtual AliHLTComponent* Spawn() {return new AliHLTBlockFilterComponent;}
135
136  protected:
137
138   /**
139    * Data processing method for the component.
140    * Filters the incoming data descriptors according to the rules and forwards
141    * them into the output.
142    * @return neg. error code if failed 
143    */
144   int DoEvent( const AliHLTComponentEventData& evtData,
145                const AliHLTComponentBlockData* blocks, 
146                AliHLTComponentTriggerData& trigData,
147                AliHLTUInt8_t* outputPtr, 
148                AliHLTUInt32_t& size,
149                AliHLTComponentBlockDataList& outputBlocks );
150   
151   using AliHLTProcessor::DoEvent;
152
153   /**
154    * Component initialisation and argument scan.
155    */
156   int DoInit( int argc, const char** argv );
157
158   /**
159    * Component cleanup.
160    */
161   int DoDeinit();
162
163  private:
164   /** copy constructor prohibited */
165   AliHLTBlockFilterComponent(const AliHLTBlockFilterComponent&);
166   /** assignment operator prohibited */
167   AliHLTBlockFilterComponent& operator=(const AliHLTBlockFilterComponent&);
168
169   /**
170    * Check if the data block is selected by the filter rules.
171    * @return 1 if selected
172    */
173   int IsSelected(const AliHLTComponentBlockData& block);
174
175   /** filtering rules, only the data type and specification members are use */
176   AliHLTComponentBlockDataList fFilterRules;                       //! transient
177
178   ClassDef(AliHLTBlockFilterComponent, 0)
179 };
180 #endif