code documentation; minor enhancement of BlockFilter
[u/mrichter/AliRoot.git] / HLT / BASE / util / AliHLTRawReaderPublisherComponent.h
1 //-*- Mode: C++ -*-
2 // @(#) $Id$
3
4 #ifndef ALIHLTRAWREADERPUBLISHERCOMPONENT_H
5 #define ALIHLTRAWREADERPUBLISHERCOMPONENT_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   AliHLTRawReaderPublisherComponent.h
11     @author Matthias Richter
12     @date   
13     @brief  A general data publisher component for the AliRawReader.
14 */
15
16 #include "AliHLTOfflineDataSource.h"
17
18 /**
19  * @class AliHLTRawReaderPublisherComponent
20  * A general data publisher component for the AliRawReader.
21  * The component publishs the data of a given detector and equipment ID.
22  * 
23  * If no data specification is given, the equipment id is used as default.
24  * A child class can implement @ref GetSpecificationFromEquipmentId to
25  * provide a different rule.
26  *
27  * The component publishes one data block for each equipment id in the
28  * give range. If the RawReader does not provide any data, an empty data
29  * block consisting of the Common Data Header is produced. 
30  * 
31  * <h2>General properties:</h2>
32  *
33  * Component ID: \b AliRawReaderPublisher                               <br>
34  * Library: \b libAliHLTUtil.so                                         <br>
35  * Input Data Types: none                                               <br>
36  * Output Data Types: according to parameters and available RAW data    <br>
37  *
38  * <h2>Mandatory arguments:</h2>
39  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
40  * The equipment id(s) must be defined by argument(s) out of:
41  * \li -detector     <i> detector name      </i>
42  *      e.g. <tt> -detector TPC </tt>
43  * \li -equipmentid  <i> id      </i>
44  *      the equipmentid within the detector, e.g. TPC 0 is 768
45  * \li -minid  <i> id      </i>
46  *      the minimum equipmentid including detector offset, e.g. 768 is TPC 0<br>
47  *      if the -detector option is used, the id is without detector offset
48  * \li -maxid  <i> id      </i>
49  *      the maximum equipmentid including detector offset (default = minid)<br>
50  *      if the -detector option is used, the id is without detector offset
51  *
52  * <h2>Optional arguments:</h2>
53  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
54  * \li -verbose<br>
55  *      print out some more info messages, mainly for the sake of tutorials
56  * \li -skipempty
57  *      skip all empty ddls in the specified range; by default, the component
58  *      generates and inserts empty data blocks
59  * \li -datatype     <i> datatype   dataorigin </i> <br>
60  *      data type ID and origin, e.g. <tt>-datatype DIGITS TPC </tt>
61  * \li -dataspec     <i> specification </i> <br>
62  *      data specification treated as decimal number or hex number if
63  *      prepended by '0x'
64  *
65  * <h2>Configuration:</h2>
66  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
67  * Configuration by component arguments.
68  *
69  * <h2>Default CDB entries:</h2>
70  * The component loads no CDB entries.
71  *
72  * <h2>Performance:</h2>
73  * The component does not process any event data.
74  *
75  * <h2>Memory consumption:</h2>
76  * The component does not process any event data.
77  *
78  * <h2>Output size:</h2>
79  * According to the available data. The component is an AliHLTDataSource
80  * and inteded to be used in the AliHLTSystem framework only. The component
81  * implements the standard AliHLTSystem adaptive buffer allocation. 
82  *
83  * @ingroup alihlt_util_components
84  */
85 class AliHLTRawReaderPublisherComponent : public AliHLTOfflineDataSource {
86  public:
87   /** standard constructor */
88   AliHLTRawReaderPublisherComponent();
89   /** destructor */
90   virtual ~AliHLTRawReaderPublisherComponent();
91
92   /**
93    * Get the id of the component.
94    * Each component is identified by a unique id.
95    * The function is pure virtual and must be implemented by the child class.
96    * @return component id (string)
97    */
98   const char* GetComponentID();
99
100   /**
101    * Get the output data type of the component.
102    * The function is pure virtual and must be implemented by the child class.
103    * @return output data type
104    */
105   AliHLTComponentDataType GetOutputDataType();
106
107   /**
108    * Get a ratio by how much the data volume is shrinked or enhanced.
109    * The function is pure virtual and must be implemented by the child class.
110    * @param constBase        <i>return</i>: additive part, independent of the
111    *                                   input data volume  
112    * @param inputMultiplier  <i>return</i>: multiplication ratio
113    * @return values in the reference variables
114    */
115   void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier );
116
117   /**
118    * Spawn function.
119    * Each component must implement a spawn function to create a new instance of 
120    * the class. Basically the function must return <i>new <b>my_class_name</b></i>.
121    * @return new class instance
122    */
123   virtual AliHLTComponent* Spawn();
124
125  protected:
126   /**
127    * Init method.
128    */
129   int DoInit( int argc, const char** argv );
130
131   /**
132    * Deinit method.
133    */
134   int DoDeinit();
135
136   /**
137    * Data source method.
138    * @param evtData       event data structure
139    * @param trigData      trigger data structure
140    * @param outputPtr     pointer to target buffer
141    * @param size          <i>input</i>: size of target buffer
142    *                      <i>output</i>:size of produced data
143    * @param outputBlocks  list to receive output block descriptors
144    * @return neg. error code if failed
145    */
146   int GetEvent( const AliHLTComponentEventData& evtData,
147                 AliHLTComponentTriggerData& trigData,
148                 AliHLTUInt8_t* outputPtr, 
149                 AliHLTUInt32_t& size,
150                 vector<AliHLTComponentBlockData>& outputBlocks );
151
152   using AliHLTOfflineDataSource::GetEvent;
153
154  protected:
155   virtual int GetSpecificationFromEquipmentId(int id, AliHLTUInt32_t &specification) const;
156
157  private:
158   /** copy constructor prohibited */
159   AliHLTRawReaderPublisherComponent(const AliHLTRawReaderPublisherComponent&);
160   /** assignment operator prohibited */
161   AliHLTRawReaderPublisherComponent& operator=(const AliHLTRawReaderPublisherComponent&);
162
163   /** max output block size, estimated during DoInit */
164   Int_t                   fMaxSize;                                //!transient
165
166   /** detector string */
167   TString                 fDetector;                               //!transient
168
169   /** min equipment id */
170   int                     fMinEquId;                               //!transient
171
172   /** max equipment id */
173   int                     fMaxEquId;                               //!transient
174
175   /** be verbose: info printouts */
176   Bool_t                  fVerbose;                                //!transient
177
178   /** data type */
179   AliHLTComponentDataType fDataType;                               //!transient
180
181   /** data specification */
182   AliHLTUInt32_t          fSpecification;                          //!transient
183
184   /** skip the generation of empty data blocks */
185   Bool_t                  fSkipEmpty;                              //!transient
186
187   ClassDef(AliHLTRawReaderPublisherComponent, 1);
188 };
189
190 #endif