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