672e6e643298db0f19ee2073128f17689cada18d
[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 used size of the buffer
265      */
266     AliHLTUInt32_t GetUsedSize() const {return fSize;}
267
268     /**
269      * Get total size of the buffer
270      */
271     AliHLTUInt32_t GetTotalSize() const {return fTotalSize;}
272
273     /**
274      * Get pointer of data buffer
275      */
276     AliHLTUInt8_t* GetPointer() const {return fPtr;}
277
278     /**
279      * Write check pattern
280      */
281     int WritePattern(const char* pattern, int size);
282
283     /**
284      * Check pattern
285      */
286     int CheckPattern(const char* pattern, int size) const;
287
288     /**
289      * Reset buffer.
290      * Data buffer remains allocated, used size set to 0
291      */
292     int Reset();
293
294     int operator==(void*) const;
295     int operator==(AliHLTUInt8_t* ptr) const {return fPtr==ptr;}
296     int operator<=(void*) const;
297     int operator>(void*) const;
298     int operator-(void*) const;
299
300     operator void*() const {return fPtr;}
301     operator AliHLTUInt8_t*() const {return fPtr;}
302
303   private:
304     /** copy constructor prohibited */
305     AliHLTRawBuffer(const AliHLTRawBuffer&);
306     /** assignment operator prohibited */
307     AliHLTRawBuffer& operator=(const AliHLTRawBuffer&);
308
309     /** size of the currently occupied partition of the buffer */
310     AliHLTUInt32_t fSize;                                          // see above
311     /** total size of the buffer, including safety margin */
312     AliHLTUInt32_t fTotalSize;                                     // see above
313     /** the buffer */
314     AliHLTUInt8_t* fPtr;                                           //! transient
315   };
316
317  private:
318   /** copy constructor prohibited */
319   AliHLTDataBuffer(const AliHLTDataBuffer&);
320   /** assignment operator prohibited */
321   AliHLTDataBuffer& operator=(const AliHLTDataBuffer&);
322
323   /* lets see if this is needed
324      AliHLTDataSegment* FindDataSegment(AliHLTComponentDataType datatype);
325   */
326
327   /**
328    * Find those data segments which match the input types of a component.
329    * @param pConsumer       the component which subscribes to the buffer
330    * @param tgtList         the list to receive the data segment descriptors
331    * @return: number of data blocks which match the input data types 
332    *          of the consumer, neg. error code if failed <br>
333    *          -EINVAL       invalid parameter <br>
334    */
335   int FindMatchingDataSegments(const AliHLTComponent* pConsumer, 
336                                vector<AliHLTDataBuffer::AliHLTDataSegment>& tgtList);
337
338   /**
339    * Reset the data buffer.
340    * Removes all consumers back to the @ref fConsumers list, deletes
341    * segments and releases the Raw Buffer.
342    */
343   int ResetDataBuffer();
344
345   //////////////////////////////////////////////////////////////////////////////
346
347   // the data description
348
349   // the data segments within this buffer
350   vector<AliHLTDataSegment> fSegments;                             // see above
351
352   // the list of all consumers which are going to subscribe to the buffer
353   vector<AliHLTConsumerDescriptor*> fConsumers;                    // see above
354   // the list of all consumers which are currently subscribed to the buffer
355   vector<AliHLTConsumerDescriptor*> fActiveConsumers;              // see above
356   // the list of all consumers which are already released for the current event
357   vector<AliHLTConsumerDescriptor*> fReleasedConsumers;            // see above
358
359   // the buffer instance
360   AliHLTRawBuffer* fpBuffer;                                       //! transient
361
362   // flags indicating the state of the buffer
363   AliHLTUInt32_t fFlags;                                           // see above
364
365   //////////////////////////////////////////////////////////////////////////////
366   // global buffer handling, internal use only
367
368   /**
369    * Create a raw buffer of a certain size.
370    * The function tries to find a buffer of the given size (or a bit bigger by a 
371    * certain margin @ref fgMargin) from the list of free buffers.
372    * If no buffer is available, a new one is created and added to the buffer handling.
373    * @param size            min. size of the requested buffer
374    * @return pointer to raw buffer
375    */
376   static AliHLTRawBuffer* CreateRawBuffer(AliHLTUInt32_t size);
377
378   /**
379    * Mark a buffer as free.
380    * After the Data Buffer has finnished using the raw buffer, it is released
381    * and added to the list of available buffers.
382    * @param pBuffer         the raw buffer to release
383    * @return >=0 if succeeded, neg. error code if failed
384    */
385   static int ReleaseRawBuffer(AliHLTRawBuffer* pBuffer);
386
387   /**
388    * Deletes all the raw buffers.
389    * When the last Data Buffer object is destructed, all raw data buffers are
390    * relesed.
391    */
392   static int DeleteRawBuffers();
393
394   /**
395    * Number of instances of AliHLTDataBuffer.
396    * The statice variable is incremented and decremented in the constructor/
397    * destructor. All internal data structures are cleaned up when the last
398    * instance is exiting.
399    */
400   static int fgNofInstances;                                       // see above
401   /** global list of free raw buffers */
402   static vector<AliHLTRawBuffer*> fgFreeBuffers;                   // see above
403   /** global list of currently active raw buffers */
404   static vector<AliHLTRawBuffer*> fgActiveBuffers;                 // see above
405   /** determines the raw buffer size margin at buffer requests */
406   static AliHLTUInt32_t fgMargin;                                  // see above
407
408   /** global instance to HLT logging class for static methods */
409   static AliHLTLogging fgLogging;                                  // see above
410
411   /** size of the safety pattern */
412   static const Int_t fgkSafetyPatternSize;                         // see above
413
414   /** the safety pattern */
415   static const char fgkSafetyPattern[];                            //!transient
416
417   //////////////////////////////////////////////////////////////////////////////
418   // internal helper functions
419
420   /**
421    * Find the consumer descriptor for a certain component and data type in 
422    * a list of consumers.<br>
423    * <b>Note:</b> There are three lists which contain the consumers in the
424    * different states.
425    * @param pConsumer       pointer to consumer component
426    * @param list            list where to search for the consumer
427    */
428   AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer,
429                                          vector<AliHLTConsumerDescriptor*> &list) const;
430
431   /**
432    * Change the state of a consumer.
433    * The state of a consumer is determined by the list it is strored in, the
434    * method moves a consumer from the source to the target list.
435    * @param pDesc           pointer to consumer descriptor
436    * @param srcList         list where the consumer is currently to be found
437    * @param tgtList         list where to move the consumer
438    */
439   int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc,
440                           vector<AliHLTConsumerDescriptor*> &srcList,
441                           vector<AliHLTConsumerDescriptor*> &tgtList);
442
443   /**
444    * Cleanup a consumer list.
445    * Release all allocated data structures. <b>Note:</b> Not the component itself!
446    */
447   int CleanupConsumerList();
448
449   ClassDef(AliHLTDataBuffer, 0)
450 };
451
452 #endif // ALIHLTDATABUFFER_H