further work on HLTOUT framework
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTOUT.h
1 //-*- Mode: C++ -*-
2 // @(#) $Id$
3
4 #ifndef ALIHLTOUT_H
5 #define ALIHLTOUT_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   AliHLTOUT.h
11     @author Matthias Richter
12     @date   
13     @brief  The control class for HLTOUT data.
14
15 // see below for class documentation
16 // or
17 // refer to README to build package
18 // or
19 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
20
21                                                                           */
22 #include <vector>
23 #include "AliHLTLogging.h"
24
25 /**
26  * @class AliHLTOUT
27  * The control class for HLTOUT data.
28  * The output of the HLT, either from the HLTOUT nodes or simulated output,
29  * is transferred and stored in the HOMER format. The AliHLTOUT class 
30  * implements scanning of the HOMER data for all HLTOUT DDL links and
31  * abstracts access to the complete HLTOUT data.
32  * 
33  */
34 class AliHLTOUT : public AliHLTLogging {
35  public:
36   /** standard constructor */
37   AliHLTOUT();
38   /** standard destructor */
39   virtual ~AliHLTOUT();
40
41   /**
42    * Get number of data blocks in the HLTOUT data
43    */
44   int GetNofDataBlocks();
45
46   /**
47    * Select the first data block of a certain data type and specification.
48    * The selection criteria can be of kAliHLTAnyDataType and/or
49    * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
50    * @param dt    [in]  data type to match                                <br>
51    * @param spec  [in]  data specification to match                       <br>
52    * @return identifier >=0 if success, neg. error code if failed         <br>
53    *                        -ENOENT if no block found                     <br>
54    *                        -EPERM if access denied (object locked)
55    */
56   int SelectFirstDataBlock(AliHLTComponentDataType dt, AliHLTUInt32_t spec);
57
58   /**
59    * Select the next data block of data type and specification of the previous
60    * call to @ref SelectFirstDataBlock.
61    * @return identifier >=0 if success, neg. error code if failed         <br>
62    *                        -ENOENT if no block found                     <br>
63    *                        -EPERM if access denied (object locked)
64    */
65   int SelectNextDataBlock();
66
67   /**
68    * Get properties of the selected data block.
69    * @param dt    [out] data type of the selected block
70    * @param spec  [out] data specification of the selected block
71    */
72   int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
73
74   /**
75    * Get buffer of the selected data block.
76    * @param pBuffer [out] buffer of the selected data block
77    * @param size    [out] size of the selected data block
78    */
79   int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
80
81   /**
82    * Release buffer after use.
83    * @param pBuffer [in]  buffer of the selected data block
84    */
85   int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
86
87   /**
88    * Locking guard for the AliHLTOUT object.
89    * If the object is locked, the selection of data blocks can not be changed.
90    */
91   class AliHLTOUTLockGuard {
92   public:
93     /** constructor */
94     AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
95     {if (fpInstance) fpInstance->fbLocked=1;}
96     /** destructor */
97     ~AliHLTOUTLockGuard()
98     {if (fpInstance) fpInstance->fbLocked=0;}
99
100   private:
101     /** standard constructor prohibited */
102     AliHLTOUTLockGuard();
103     /** copy constructor prohibited */
104     AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
105     /** assignment operator prohibited */
106     AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
107
108     /** the AliHLTOUT instance the guard is locking */
109     AliHLTOUT* fpInstance; //!transient
110   };
111
112   /**
113    * Block descriptor.
114    */
115   class AliHLTOUTBlockDescriptor {
116   public:
117     AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index)
118       : fDataType(dt), fSpecification(spec), fIndex(index) {};
119     ~AliHLTOUTBlockDescriptor() {}
120
121     operator AliHLTComponentDataType() const {return fDataType;}
122     operator AliHLTUInt32_t() const {return fSpecification;}
123     int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
124     int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
125
126     AliHLTUInt32_t GetIndex() const {return fIndex;}
127   private:
128     /** data type of the block */
129     AliHLTComponentDataType fDataType; //!transient
130     /** data specification of the block */
131     AliHLTUInt32_t          fSpecification; //!transient
132     /** index in the data stream */
133     AliHLTUInt32_t          fIndex; //!transient
134   };
135
136  protected:
137   /**
138    * Add a block descriptor.
139    * This is done by the child classes generating the index. The AliHLTOUT
140    * object must be locked for index generation.
141    * @param desc    the block descriptor
142    * @return 0 if success, -EPERM if access denied
143    */
144   int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
145
146  private:
147   /** copy constructor prohibited */
148   AliHLTOUT(const AliHLTOUT&);
149   /** assignment operator prohibited */
150   AliHLTOUT& operator=(const AliHLTOUT&);
151
152   /**
153    * Generate the index of the HLTOUT data.
154    * Must be implemented by the child classes.
155    */
156   virtual int GenerateIndex()=0;
157
158   /**
159    * Get the data buffer
160    * @param index   [in]  index of the block
161    * @param pBuffer [out] buffer of the selected data block
162    * @param size    [out] size of the selected data block
163    */
164   virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer, 
165                             AliHLTUInt32_t& size)=0;
166
167   /** data type for the current block search, set from @ref SelectFirstDataBlock */
168   AliHLTComponentDataType fSearchDataType; //!transient
169
170   /** data specification for the current block search */
171   AliHLTUInt32_t fSearchSpecification; //!transient
172
173   /** instance locked or not */
174   int fbLocked; //!transient
175
176   /** list of block descriptors */
177   vector<AliHLTOUTBlockDescriptor> fBlockDescList; //!transient
178
179   /** current position in the list */
180   vector<AliHLTOUTBlockDescriptor>::iterator fCurrent; //!transient
181
182   /** data buffer under processing */
183   const AliHLTUInt8_t* fpBuffer; //!transient
184
185   ClassDef(AliHLTOUT, 0)
186 };
187 #endif