adding availability check for a list of OCDB objects, code cleanup and updated docume...
[u/mrichter/AliRoot.git] / HLT / rec / AliRawReaderHLT.h
1 //-*- Mode: C++ -*-
2 // $Id$
3
4 #ifndef ALIRAWREADERHLT_H
5 #define ALIRAWREADERHLT_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   AliRawReaderHLT.h
11     @author Matthias Richter
12     @date   
13     @brief  AliRawReader implementation which replaces original input of
14             detectors with the appropriate HLT output.                    */
15
16 // see below for class documentation
17 // or
18 // refer to README to build package
19 // or
20 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
21
22 #include "AliHLTDataTypes.h"
23 #include "AliRawReader.h"      // RAW, base class
24 #include "TString.h"
25 #include <vector>
26
27 class AliHLTOUT;
28 class AliHLTOUTHandler;
29 class AliHLTPluginBase;
30
31 /**
32  * @class AliRawReaderHLT
33  * A specific AliRawReader for detector input replacement by HLTOUT data blocks.
34  *
35  * HLT components can produce output data in the detector ddl raw format.
36  * Data blocks of this format can be fed into the normal detector reconstruction
37  * without changes in the actual reconstruction code by means of the
38  * AliRawReaderHLT implementation of the AliRawReader.
39  *
40  * @section sec_alirawreaderhlt_concept Conceptual design
41  * The AliRawReader provides an abstract interface to the ddl raw data. All
42  * reconstruction code uses this interface to access the data.
43  * HLT components can send their data in the original ddl raw format. The only
44  * difference of such data blocks is the location since they are shipped as
45  * part of the HLTOUT data stream. The AliRawReaderHLT provides redirection of
46  * those data blocks.
47  *
48  * The AliRawReaderHLT needs the original AliRawReader in order to get the
49  * data. Furthermore, a string containing the detector specification defines
50  * which data should be read from the HLT stream and which from the original
51  * reader.
52  *
53  * @note An HLTOUT handler must be available for the HLTOUT data blocks to
54  * be redirected. Please read @ref sec_alirawreaderhlt_module carefully.
55  *
56  * @section sec_alirawreaderhlt_usage   Selection of the HLTOUT data stream
57  * The input data of a detector can be replaced by the corresponding HLT
58  * data by calling the <tt>AliReconstruction::SetUseHLTData("...")</tt>, e.g.
59  * <pre>
60  *    AliReconstruction rec;
61  *    rec.SetUseHLTData("TPC TRD");
62  * </pre>
63  * will replace the input of TPC and TRD.
64  *
65  * The reader can be used directly. In order to avoid library dependencies
66  * downwards, the methed AliRawHLTManager::CreateRawReaderHLT is available
67  * in the RAW package.
68  * <pre>
69  * {
70  *   AliRawReader* orgReader=AliRawReader::Create("raw.root");
71  *   AliRawReader* rawreader=AliRawHLTManager::CreateRawReaderHLT(orgReader, "ITSSDD");
72  *   rawreader->Select("ITSSDD");
73  *   int count=0;
74  *   while (rawreader->NextEvent()) {
75  *     cout << "scanning event " << count++ << endl;
76  *     UChar_t* pSrc=NULL;
77  *     while (rawreader->ReadNextData(pSrc)) {
78  *       cout << "  equipment: " << rawreader->GetEquipmentId() << endl;
79  *     }
80  *   }
81  * }
82  * </pre>
83  *
84  * @section sec_alirawreaderhlt_detectorids  Detector selection
85  * The constructor gets a detector selection string as parameter and initializes
86  * the redirection according to that. Detector Ids are according to AliDAQ.
87  * Please note the special strings for for ITS and MUON sub-detectors, ITSSPD,
88  * ITSSDD, ITSSSD, and MUONTRK and MUONTRG respectively.
89  *
90  * @section sec_alirawreaderhlt_module  Module implementation
91  * In order to determine the equipment id for the data block, the HLT module
92  * must implement an HLTOUT handler of class AliHLTOUTHandlerEquId which is of 
93  * type @ref AliHLTModuleAgent::AliHLTOUTHandlerType ::kRawReader.
94  * The handler must implement the method
95  * <pre>
96  *  // AliHLTOUTHandlerEquId::ProcessData(AliHLTOUT*)
97  *  virtual int ProcessData(AliHLTOUT* pData);
98  * </pre>
99  * which returns the equipment id and eventually decodes data to be retrieved
100  * by calling AliHLTOUTHandler::GetProcessedData(). If the equipment id of the
101  * DDL has been sent as data specification of the block, the AliHLTOUTHandlerEquId
102  * can be used directly.
103  *
104  * Secondly, the AliHLTModuleAgent implementation of the module has to create
105  * the handler for the data blocks. Depending on the data type and specification,
106  * the the following interface methods return handler description and handler. 
107  * <pre>
108  *   int AliHLTModuleAgent::GetHandlerDescription(AliHLTComponentDataType dt,
109  *                                                AliHLTUInt32_t spec,
110  *                                                AliHLTOUTHandlerDesc& desc) const;
111  *
112  *   AliHLTOUTHandler* AliHLTModuleAgent::GetOutputHandler(AliHLTComponentDataType dt, 
113  *                                                         AliHLTUInt32_t spec);
114  * </pre>
115  * See section @ref tut_alirawreaderhlt for sample implementation.
116  *
117  * @ingroup alihlt_aliroot_reconstruction
118  */
119 class AliRawReaderHLT : public AliRawReader {
120  public:
121   /** constructor */
122   AliRawReaderHLT(AliRawReader* pParentReader, const char* options=NULL);
123   /** destructor */
124   virtual ~AliRawReaderHLT();
125
126   // interface methods of AliRawReader
127   void     Select(Int_t detectorID, 
128                   Int_t minDDLID = -1, Int_t maxDDLID = -1);
129 //   void     Select(const char *detectorName, 
130 //                Int_t minDDLID = -1, Int_t maxDDLID = -1);
131
132   using AliRawReader::Select;
133
134   void     SelectEquipment(Int_t equipmentType, 
135                            Int_t minEquipmentId = -1, 
136                            Int_t maxEquipmentId = -1);
137   void     SkipInvalid(Bool_t skip = kTRUE);
138   //  void     SelectEvents(Int_t type);
139
140   UInt_t   GetType() const;
141   UInt_t   GetRunNumber() const;
142   const UInt_t* GetEventId() const;
143   const UInt_t* GetTriggerPattern() const;
144   const UInt_t* GetDetectorPattern() const;
145   const UInt_t* GetAttributes() const;
146   const UInt_t* GetSubEventAttributes() const;
147   UInt_t   GetLDCId() const;
148   UInt_t   GetGDCId() const;
149   UInt_t   GetTimestamp() const;
150
151   const UInt_t* GetEquipmentAttributes() const;
152   Int_t    GetEquipmentElementSize() const;
153   Int_t    GetEquipmentHeaderSize() const;
154
155   Int_t    GetEquipmentSize() const;
156   Int_t    GetEquipmentType() const;
157   Int_t    GetEquipmentId() const;
158   Bool_t   ReadHeader();
159   Bool_t   ReadNextData(UChar_t*& data);
160   Bool_t   ReadNextInt(UInt_t& data);
161   Bool_t   ReadNextShort(UShort_t& data);
162   Bool_t   ReadNextChar(UChar_t& data);
163   Bool_t   ReadNext(UChar_t* data, Int_t size);
164
165   Bool_t   Reset();
166
167   Bool_t   NextEvent();
168   Bool_t   RewindEvents();
169
170  protected:
171
172  private:
173   /** standard constructor prohibited */
174   AliRawReaderHLT();
175   /** copy constructor prohibited */
176   AliRawReaderHLT(const AliRawReaderHLT&);
177   /** assignment operator prohibited */
178   AliRawReaderHLT& operator=(const AliRawReaderHLT&);
179
180   /**
181    * Scan the options.
182    * Set the ids for the specified detectors in the detector
183    * list. Currently, no other options are available.
184    */
185   int ScanOptions(const char* options);
186
187   /**
188    * Read the next data block from the HLT stream
189    */
190   Bool_t ReadNextHLTData();
191
192   /**
193    * Check if a ddlid is part of the ones which are selected for
194    * input replacement.
195    */
196   Bool_t IsHLTInput(int ddlid);
197
198   /**
199    * Check if redirection is enabled for at least one detector in the
200    * selected range.
201    * Set the fbHaveHLTData variable
202    * @return true if data has to be read from the HLT stream.
203    */
204   Bool_t EvaluateSelection();
205
206   /**
207    * Release the current HLT data.
208    * Releases the current buffer of either the active HLTOUT data
209    * block handler or the HLTOUT instance. The latter implies a
210    * reset of the reader concerning the HLT data blocks.
211    * @param bReleaseHLTOUT   release HLTOUT instance if \em true
212    *                         only current data buffer if \em false
213    * @return neg. error code if failed
214    */
215   int ReleaseHLTData(bool bReleaseHLTOUT=true);
216
217   /**
218    * Backbone of all Read functions.
219    * Reads the next data into the internal buffer and switches to next
220    * block if enabled.
221    *
222    * @param data             target to receive pointer
223    * @param readHeader       kTRUE: switch to next block if no more data
224    */
225   Bool_t   ReadNextData(UChar_t*& data, Bool_t readHeader);
226
227   /** the rawreader */
228   AliRawReader* fpParentReader; //!transient
229
230   /** options */
231   TString fOptions; //!transient
232
233   /** system options = options w/o detector strings */
234   TString fSystemOptions; //!transient
235
236   /** current data set, either extracted from the HLT stream or parent raw reader */
237   const AliHLTUInt8_t* fpData; // !transient
238
239   /** size of the current data set */
240   int fDataSize; // !transient
241
242   /** current stream offset in the data set */
243   int fOffset; // !transient
244
245   /** current stream position for the ReadNextData function */
246   int fPosition; // !transient
247
248   /** equipment id of the current data set, >0 indicates data set from HLT stream */
249   int fEquipmentId; // !transient
250
251   /** indicates the availibility of data from the HLT stream */
252   bool fbHaveHLTData; // !transient
253
254   /** list of detectors for which data will be taken from HLT stream */
255   vector<int> fDetectors; // !transient
256
257   /** instance of the HLTOUT handler */
258   AliHLTOUT* fpHLTOUT; // !transient
259
260   /** start reading HLTOUT from beginning */
261   bool fbReadFirst; //!transient
262
263   /** instance of the data handler providing the current data buffer */
264   AliHLTOUTHandler* fpDataHandler; // !transient
265
266   /** base class for AliRoot HLT plugins */
267   AliHLTPluginBase* fpPluginBase;                                     //!transient
268
269   ClassDef(AliRawReaderHLT, 5)
270 };
271
272 #define ALIHLTREC_LIBRARY                   "libHLTrec.so"
273 #define ALIHLTREC_LIBRARY_VERSION           0
274 #define ALIRAWREADERHLT_CREATE_INSTANCE     "AliRawReaderHLTCreateInstance"
275
276 #ifdef __cplusplus
277 extern "C" {
278 #endif
279   typedef AliRawReader* (*AliRawReaderHLTCreateInstance_t)(AliRawReader* pParentReader, const char* options);
280
281   /**
282    * Create an instance of the AliRawReader class
283    */
284   AliRawReader* AliRawReaderHLTCreateInstance(AliRawReader* pParentReader, const char* options);
285 #ifdef __cplusplus
286 }
287 #endif
288 #endif