c766d3ae94700ae813bbeb6f4b3d8715fb966e1a
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTDataBuffer.h
1 // @(#) $Id$
2
3 #ifndef ALIHLTDATABUFFER_H
4 #define ALIHLTDATABUFFER_H
5 /* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
6  * See cxx source for full Copyright notice                               */
7
8 /** @file   AliHLTDataBuffer.h
9     @author Matthias Richter
10     @date   
11     @brief  Handling of Data Buffers for HLT components.
12     @note   The class is used in Offline (AliRoot) context
13 */
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 #include <vector>
22 #include "AliHLTLogging.h"
23 #include "AliHLTDataTypes.h"
24 #include "TObject.h"
25
26 class AliHLTComponent;
27 class AliHLTConsumerDescriptor;
28
29 /**
30  * @class AliHLTDataBuffer
31  * @brief  Handling of data buffers for the HLT.
32  * 
33  * The class provides handling of data buffers for HLT tasks. Each task gets
34  * its own Data Buffer instance. The buffer is grouped into different data
35  * segments according to the output of the component.<br>
36  * The Data Buffer keeps control over the data requests of the 'child'
37  * components. Each component can subscribe to a certain segment of the data
38  * buffer. It's state is then changed from 'reserved' to 'active'. After the
39  * data processing, the component has to release the segment and it's state is
40  * set to 'processed'. If all components have requested and released their data,
41  * the Raw Buffer is released and pushed back in the list of available buffers.
42  *
43  * @note This class is only used for the @ref alihlt_system.
44  *
45  * @ingroup alihlt_system
46  */
47 class AliHLTDataBuffer : public TObject, public AliHLTLogging 
48 {
49  public:
50   //////////////////////////////////////////////////////////////////////////////
51   // constructors and destructors
52
53   /* standard constructor
54    */
55   AliHLTDataBuffer();
56   /** destructor */
57   virtual ~AliHLTDataBuffer();
58
59   //////////////////////////////////////////////////////////////////////////////
60   // initialization
61
62   /**
63    * Add component to the list of consumers
64    * @param pConsumer - a consumer of type AliHLTComponent
65    */
66   int SetConsumer(AliHLTComponent* pConsumer);
67
68   //////////////////////////////////////////////////////////////////////////////
69   // component to component communication
70
71   /**
72    * Determine the number of matching data blocks for the component and a
73    * consumer component. <br>
74    * The first approach will support only one output data type for processing
75    * components.
76    * @param pConsumer       the component which subscribes to the buffer
77    * @param tgtList         (optional) the list to receive the data types
78    * @return: number of data blocks which match the input data types 
79    *          of the consumer, neg. error code if failed <br>
80    *          -EINVAL       invalid parameter <br>
81    */
82   int FindMatchingDataBlocks(const AliHLTComponent* pConsumer,
83                              vector<AliHLTComponentDataType>* tgtList=NULL);
84
85   /**
86    * Subscribe to a segment of the data buffer.
87    * The function prepares the block descriptor for subsequent use with the
88    * AliHLTComponent::ProcessEvent method, the method can prepare several block
89    * descriptors up to the array size specified by iArraySize. The return value
90    * is independent from the array size the number of block descriptors which
91    * would have been prepared if there was enough space in the array<br>
92    * The method is used by the consumer component.
93    * @param pConsumer       the component which subscribes to the buffer
94    * @param arrayBlockDesc  pointer to block descriptor to be filled
95    * @param iArraySize      size of the block descriptor array
96    * @return: number of matching data blocks, neg. error code if failed<br>
97    *          -EACCESS      the consumer state can't be changed (activated)
98    *          -EBADF        unresolved data segments <br>
99    *          -ENOENT       consumer component not found <br>
100    *          -ENODATA      data buffer does not have raw data <br>
101    *          -EINVAL       invalid parameter <br>
102    */
103   int Subscribe(const AliHLTComponent* pConsumer,
104                 AliHLTComponentBlockData* arrayBlockDesc,
105                 int iArraySize);
106
107   /**
108    * Release an instance of the data buffer.
109    * Resets the variables of the block descriptor.
110    * If all buffer segments are released, the Data Buffer is reseted
111    * and the Raw Buffer released.<br>
112    * The method is used by the consumer component.
113    * @param pBlockDesc      descriptor of the data segment
114    * @param pConsumer       the component which subscribes to the buffer
115    * @return: >0 if success, negative error code if failed <br>
116    *          -EACCESS      the consumer state can not be changed (de-activated)
117    *          -ENOENT       consumer has not subscribed to the buffer <br>
118    *          -EINVAL       invalid parameter <br>
119    */
120   int Release(AliHLTComponentBlockData* pBlockDesc, const AliHLTComponent* pConsumer);
121
122   /**
123    * Get a target buffer of minimum size iMinSize.
124    * The method is used by the component which owns the Data Buffer to 
125    * allocate a buffer for the data it is going to produce.
126    * @param iMinSize        minumum size of the requested buffer
127    * @return: pointer to target buffer if 
128    */
129   AliHLTUInt8_t* GetTargetBuffer(int iMinSize);
130
131   /**
132    * Set the segments for the data buffer.
133    * This is usually done after the component has written the data to the buffer, 
134    * which was requested by the @ref GetTargetBuffer method. The component might
135    * produce different types of data, for each type a segment has to be defined
136    * which describes the data inside the buffer.<br>
137    * The @ref AliHLTComponentBlockData segment descriptor comes directly from
138    * the @ref AliHLTComponent::ProcessEvent method.
139    * @param pTgt            the target buffer which the segments refer to
140    * @param arraySegments   the output block descriptors of the component
141    * @param iSize           size of the array
142    */
143   int SetSegments(AliHLTUInt8_t* pTgt, AliHLTComponentBlockData* arraySegments, int iSize);
144
145   /**
146    * Check if the data buffer is empty.
147    * @return 1 if empty, 0 if not
148    */
149   int IsEmpty();
150
151   /**
152    * Get the total and maximum size of the buffer.
153    * Lets see if this is needed later
154    */
155   //int GetTotalSize();
156
157   /**
158    * Get the number of segments
159    * @return number of segments
160    */
161   int GetNofSegments();
162
163   /**
164    * Get the total number of consumers.
165    * This gives the number of consumers regardless of their state.
166    * @return number of consumers
167    */
168   int GetNofConsumers();
169
170   /**
171    * Get the number of consumers which still need to be processed during
172    * the current event.
173    * @return number of consumers
174    */
175   int GetNofPendingConsumers();
176
177   /**
178    * Get the number of consumers currently under processing.
179    * @return number of active consumers
180    */
181   int GetNofActiveConsumers();
182
183   /**
184    * Check if a consumer is already in the list
185    * @param pConsumer   pointer to consumer component
186    * @param bAllLists   search in all lists if 1
187    *                    search only in fConsumer list if 0
188    * @return 1 if found, 0 if not
189    */
190   int FindConsumer(AliHLTComponent* pConsumer, int bAllLists=1);
191
192   /**
193    * Public method to reset the buffer.
194    * Eventually with some additional checks. In normal operation,
195    * an external reset should not be necessary.
196    */
197   int Reset();
198
199   /**
200    * @class AliHLTDataSegment
201    * @brief  Descriptor of a data segment within the buffer.
202    */
203   class AliHLTDataSegment {
204   friend class AliHLTDataBuffer;
205   friend class AliHLTConsumerDescriptor;
206   public:
207     AliHLTDataSegment()
208       :
209       fDataType(),
210       fSegmentOffset(0),
211       fSegmentSize(0),
212       fSpecification(0)
213     {
214       memset(&fDataType, 0, sizeof(AliHLTComponentDataType));
215     }
216     AliHLTDataSegment(AliHLTUInt32_t offset, AliHLTUInt32_t size) 
217       :
218       fDataType(),
219       fSegmentOffset(offset),
220       fSegmentSize(size),
221       fSpecification(0)
222     {
223       memset(&fDataType, 0, sizeof(AliHLTComponentDataType));
224     }
225   private:
226     /** the data type of this segment */
227     AliHLTComponentDataType fDataType;                             // see above
228     /** offset in byte within the data buffer */
229     AliHLTUInt32_t fSegmentOffset;                                 // see above
230     /** size of the actual content */
231     AliHLTUInt32_t fSegmentSize;                                   // see above
232     /** data specification */
233     AliHLTUInt32_t fSpecification;                                 // see above
234   };
235
236   /**
237    * @class AliHLTRawBuffer
238    * @brief  Descriptor of the raw data buffer which can host several segments.
239    */
240   class AliHLTRawBuffer {
241   public:
242     /** standard constructor */
243     AliHLTRawBuffer() : fSize(0), fTotalSize(0), fPtr(NULL) {}
244     /** constructor */
245     AliHLTRawBuffer(AliHLTUInt32_t size);
246     /** destructor */
247     virtual ~AliHLTRawBuffer();
248
249     /**
250      * Use a fraction of the buffer.
251      * @param size    size in bytes to be used
252      * @return pointer to buffer
253      */
254     AliHLTUInt8_t* UseBuffer(AliHLTUInt32_t size);
255
256     /**
257      * Check whether buffer fits for a request.
258      * @param size    size of the request in bytes
259      * @return 1 if buffer is big enough, 0 if not
260      */
261     int CheckSize(AliHLTUInt32_t size) const;
262
263     /**
264      * Get total size of the buffer
265      */
266     AliHLTUInt32_t GetTotalSize() const {return fTotalSize;}
267
268     /**
269      * Write check pattern
270      */
271     int WritePattern(const char* pattern, int size);
272
273     /**
274      * Check pattern
275      */
276     int CheckPattern(const char* pattern, int size) const;
277
278     /**
279      * Reset buffer.
280      * Data buffer remains allocated, used size set to 0
281      */
282     int Reset();
283
284     int operator==(void*) const;
285     int operator==(AliHLTUInt8_t* ptr) const {return fPtr==ptr;}
286     int operator<=(void*) const;
287     int operator>(void*) const;
288     int operator-(void*) const;
289
290     operator void*() const {return fPtr;}
291     operator AliHLTUInt8_t*() const {return fPtr;}
292
293     operator AliHLTUInt32_t() const {return fSize;}
294
295   private:
296     /** copy constructor prohibited */
297     AliHLTRawBuffer(const AliHLTRawBuffer&);
298     /** assignment operator prohibited */
299     AliHLTRawBuffer& operator=(const AliHLTRawBuffer&);
300
301     /** size of the currently occupied partition of the buffer */
302     AliHLTUInt32_t fSize;                                          // see above
303     /** total size of the buffer, including safety margin */
304     AliHLTUInt32_t fTotalSize;                                     // see above
305     /** the buffer */
306     AliHLTUInt8_t* fPtr;                                           //! transient
307   };
308
309  private:
310   /** copy constructor prohibited */
311   AliHLTDataBuffer(const AliHLTDataBuffer&);
312   /** assignment operator prohibited */
313   AliHLTDataBuffer& operator=(const AliHLTDataBuffer&);
314
315   /* lets see if this is needed
316      AliHLTDataSegment* FindDataSegment(AliHLTComponentDataType datatype);
317   */
318
319   /**
320    * Find those data segments which match the input types of a component.
321    * @param pConsumer       the component which subscribes to the buffer
322    * @param tgtList         the list to receive the data segment descriptors
323    * @return: number of data blocks which match the input data types 
324    *          of the consumer, neg. error code if failed <br>
325    *          -EINVAL       invalid parameter <br>
326    */
327   int FindMatchingDataSegments(const AliHLTComponent* pConsumer, 
328                                vector<AliHLTDataBuffer::AliHLTDataSegment>& tgtList);
329
330   /**
331    * Reset the data buffer.
332    * Removes all consumers back to the @ref fConsumers list, deletes
333    * segments and releases the Raw Buffer.
334    */
335   int ResetDataBuffer();
336
337   //////////////////////////////////////////////////////////////////////////////
338
339   // the data description
340
341   // the data segments within this buffer
342   vector<AliHLTDataSegment> fSegments;                             // see above
343
344   // the list of all consumers which are going to subscribe to the buffer
345   vector<AliHLTConsumerDescriptor*> fConsumers;                    // see above
346   // the list of all consumers which are currently subscribed to the buffer
347   vector<AliHLTConsumerDescriptor*> fActiveConsumers;              // see above
348   // the list of all consumers which are already released for the current event
349   vector<AliHLTConsumerDescriptor*> fReleasedConsumers;            // see above
350
351   // the buffer instance
352   AliHLTRawBuffer* fpBuffer;                                       //! transient
353
354   // flags indicating the state of the buffer
355   AliHLTUInt32_t fFlags;                                           // see above
356
357   //////////////////////////////////////////////////////////////////////////////
358   // global buffer handling, internal use only
359
360   /**
361    * Create a raw buffer of a certain size.
362    * The function tries to find a buffer of the given size (or a bit bigger by a 
363    * certain margin @ref fgMargin) from the list of free buffers.
364    * If no buffer is available, a new one is created and added to the buffer handling.
365    * @param size            min. size of the requested buffer
366    * @return pointer to raw buffer
367    */
368   static AliHLTRawBuffer* CreateRawBuffer(AliHLTUInt32_t size);
369
370   /**
371    * Mark a buffer as free.
372    * After the Data Buffer has finnished using the raw buffer, it is released
373    * and added to the list of available buffers.
374    * @param pBuffer         the raw buffer to release
375    * @return >=0 if succeeded, neg. error code if failed
376    */
377   static int ReleaseRawBuffer(AliHLTRawBuffer* pBuffer);
378
379   /**
380    * Deletes all the raw buffers.
381    * When the last Data Buffer object is destructed, all raw data buffers are
382    * relesed.
383    */
384   static int DeleteRawBuffers();
385
386   /**
387    * Number of instances of AliHLTDataBuffer.
388    * The statice variable is incremented and decremented in the constructor/
389    * destructor. All internal data structures are cleaned up when the last
390    * instance is exiting.
391    */
392   static int fgNofInstances;                                       // see above
393   /** global list of free raw buffers */
394   static vector<AliHLTRawBuffer*> fgFreeBuffers;                   // see above
395   /** global list of currently active raw buffers */
396   static vector<AliHLTRawBuffer*> fgActiveBuffers;                 // see above
397   /** determines the raw buffer size margin at buffer requests */
398   static AliHLTUInt32_t fgMargin;                                  // see above
399
400   /** global instance to HLT logging class for static methods */
401   static AliHLTLogging fgLogging;                                  // see above
402
403   /** size of the safety pattern */
404   static const Int_t fgkSafetyPatternSize;                         // see above
405
406   /** the safety pattern */
407   static const char fgkSafetyPattern[];                            //!transient
408
409   //////////////////////////////////////////////////////////////////////////////
410   // internal helper functions
411
412   /**
413    * Find the consumer descriptor for a certain component and data type in 
414    * a list of consumers.<br>
415    * <b>Note:</b> There are three lists which contain the consumers in the
416    * different states.
417    * @param pConsumer       pointer to consumer component
418    * @param list            list where to search for the consumer
419    */
420   AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer,
421                                          vector<AliHLTConsumerDescriptor*> &list) const;
422
423   /**
424    * Change the state of a consumer.
425    * The state of a consumer is determined by the list it is strored in, the
426    * method moves a consumer from the source to the target list.
427    * @param pDesc           pointer to consumer descriptor
428    * @param srcList         list where the consumer is currently to be found
429    * @param tgtList         list where to move the consumer
430    */
431   int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc,
432                           vector<AliHLTConsumerDescriptor*> &srcList,
433                           vector<AliHLTConsumerDescriptor*> &tgtList);
434
435   /**
436    * Cleanup a consumer list.
437    * Release all allocated data structures. <b>Note:</b> Not the component itself!
438    */
439   int CleanupConsumerList();
440
441   ClassDef(AliHLTDataBuffer, 0)
442 };
443
444 #endif // ALIHLTDATABUFFER_H