ALIROOT-5600 - skip non-participating detector modules
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTDomainEntry.h
1 //-*- Mode: C++ -*-
2 // $Id$
3 #ifndef ALIHLTDOMAINENTRY_H
4 #define ALIHLTDOMAINENTRY_H
5 /* This file is property of and copyright by the ALICE HLT Project        *
6  * ALICE Experiment at CERN, All rights reserved.                         *
7  * See cxx source for full Copyright notice                               */
8
9 /// @file   AliHLTDomainEntry.h
10 /// @author Artur Szostak <artursz@iafrica.com>
11 /// @date   20 Nov 2008
12 /// @brief  Declaration of the AliHLTDomainEntry class used to store identifying information about HLT data blocks.
13
14 #include "TObject.h"
15 #include "AliHLTDataTypes.h"
16
17 class TString;
18
19 /**
20  * \class AliHLTDomainEntry
21  * The AliHLTDomainEntry class is used to store information identifying a particular
22  * HLT internal data block, or set of data blocks using wild card values. This
23  * class is used by AliHLTTriggerDomain to store a list of data block classes
24  * that should be readout by the HLT. The information identifying a data block is
25  * the following:
26  *  - the data block type
27  *  - the data block's origin (detector name)
28  *  - the data block's specification (detector specific bits)
29  * Several useful operators and methods are defined to help manipulate this
30  * information in the AliHLTTriggerDomain class.
31  */
32 class AliHLTDomainEntry : public TObject
33 {
34  public:
35   
36   /**
37    * Default constructor.
38    */
39   AliHLTDomainEntry();
40   
41   /**
42    * Copy constructor performs a deep copy.
43    * \param domain  The domain entry to copy from.
44    */
45   AliHLTDomainEntry(const AliHLTDomainEntry& domain);
46   
47   /**
48    * This constructs a domain entry with a particular data type and an 'any' wild
49    * card value for specification indicating any specification will match.
50    * \param type  The data block type and origin to use.
51    */
52   AliHLTDomainEntry(const AliHLTComponentDataType& type);
53   
54   /**
55    * This constructs a domain entry with a particular data type and origin. The
56    * specification is marked as an 'any' wild card value, indicating any data
57    * block specification will match.
58    * \param blocktype  The data block type string of the data block. The value
59    *    kAliHLTAnyDataTypeID can be used to specify the any type wild card value.
60    * \param origin  The origin of the data block, such as the detector name.
61    *    The value kAliHLTDataOriginAny can be used to specify the any origin
62    *    wild card value.
63    */
64   AliHLTDomainEntry(const char* blocktype, const char* origin);
65   
66   /**
67    * This constructs a domain entry with a particular data type, origin and
68    * specification.
69    * \param type  The data block type and origin to use.
70    * \param spec  The data block specification to use.
71    */
72   AliHLTDomainEntry(const AliHLTComponentDataType& type, UInt_t spec);
73   
74   /**
75    * This constructs a domain entry with a particular data type, origin and
76    * specification.
77    * \param blocktype  The data block type string of the data block. The value
78    *    kAliHLTAnyDataTypeID can be used to specify the any type wild card value.
79    * \param origin  The origin of the data block, such as the detector name.
80    *    The value kAliHLTDataOriginAny can be used to specify the any origin
81    *    wild card value.
82    * \param spec  The data block specification to use.
83    */
84   AliHLTDomainEntry(const char* blocktype, const char* origin, UInt_t spec);
85   
86   /**
87    * The constructor deep copies the domain entry but overrides the exclude flag.
88    * \param exclude  The new exclude flag value to use. If 'true' then the entry
89    *    forms part of a trigger domain exclusion rule.
90    * \param domain  The domain entry to copy from.
91    */
92   AliHLTDomainEntry(Bool_t exclude, const AliHLTDomainEntry& domain);
93   
94   /**
95    * This constructs a domain entry with a particular data type and exclude flag
96    * value, but an 'any' wild card value is used for the data block specification.
97    * \param exclude  The exclude flag value to use. If 'true' then the entry forms
98    *    part of a trigger domain exclusion rule.
99    * \param type  The data block type and origin to use.
100    */
101   AliHLTDomainEntry(Bool_t exclude, const AliHLTComponentDataType& type);
102   
103   /**
104    * This constructs a domain entry with a particular data type, origin and exclusion
105    * value. The specification is marked as an 'any' wild card value, indicating any
106    * data block specification will match.
107    * \param exclude  The exclude flag value to use. If 'true' then the entry forms
108    *    part of a trigger domain exclusion rule.
109    * \param blocktype  The data block type string of the data block. The value
110    *    kAliHLTAnyDataTypeID can be used to specify the any type wild card value.
111    * \param origin  The origin of the data block, such as the detector name.
112    *    The value kAliHLTDataOriginAny can be used to specify the any origin
113    *    wild card value.
114    */
115   AliHLTDomainEntry(Bool_t exclude, const char* blocktype, const char* origin);
116   
117   /**
118    * This constructs a domain entry with a particular exclude flag value, data type,
119    * origin and specification.
120    * \param exclude  The exclude flag value to use. If 'true' then the entry forms
121    *    part of a trigger domain exclusion rule.
122    * \param type  The data block type and origin to use.
123    * \param spec  The data block specification to use.
124    */
125   AliHLTDomainEntry(Bool_t exclude, const AliHLTComponentDataType& type, UInt_t spec);
126   
127   /**
128    * This constructs a domain entry with a particular exclude flag value, data type,
129    * origin and specification.
130    * \param exclude  The exclude flag value to use. If 'true' then the entry forms
131    *    part of a trigger domain exclusion rule.
132    * \param blocktype  The data block type string of the data block. The value
133    *    kAliHLTAnyDataTypeID can be used to specify the any type wild card value.
134    * \param origin  The origin of the data block, such as the detector name.
135    *    The value kAliHLTDataOriginAny can be used to specify the any origin
136    *    wild card value.
137    * \param spec  The data block specification to use.
138    */
139   AliHLTDomainEntry(Bool_t exclude, const char* blocktype, const char* origin, UInt_t spec);
140   
141   /**
142    * Default destructor.
143    */
144   virtual ~AliHLTDomainEntry();
145   
146   /**
147    * Returns the value of the exclude flag.
148    * \return  true if the domain entry is an exclusion and the matching data blocks
149    *    should not form part of the trigger domain for readout.
150    */
151   Bool_t Exclusive() const { return fExclude; }
152   
153   /**
154    * Sets the value of the exclude flag.
155    * \param value  The value to set the flag to. If 'true' then the domain entry
156    *    is an exclusion and the matching data blocks should not form part of the
157    *    trigger domain for readout. If 'false' then the matching data blocks should
158    *    form part of the readout.
159    */
160   void Exclusive(Bool_t value) { fExclude = value; }
161   
162   /**
163    * Indicates if the domain entry is an inclusive rule.
164    * \return  true if the domain entry is an inclusion and the matching data blocks
165    *    should form part of the trigger domain for readout.
166    */
167   Bool_t Inclusive() const { return ! fExclude; }
168   
169   /**
170    * Used to set if the domain entry should be an inclusion or exclusion.
171    * \param value  The value to set. If 'true' then the domain entry is an inclusion
172    *    and the matching data blocks should form part of the trigger domain for readout.
173    *    If 'false' then the matching data blocks should not form part of the readout.
174    */
175   void Inclusive(Bool_t value) { fExclude = ! value; }
176   
177   /**
178    * Returns the data type of the domain entry.
179    * \return  The data type that data blocks are compared to.
180    */
181   const AliHLTComponentDataType& DataType() const { return fType; }
182   
183   /**
184    * Indicates if the specification is used.
185    * \return  true if the specification is used when matching data blocks, otherwise
186    *     false, indicating that the specification is treated as a wild card value.
187    */
188   Bool_t IsValidSpecification() const { return fUseSpec; }
189   
190   /**
191    * Returns the data block specification of the domain entry.
192    * \return  The data block specification that data blocks are compared to.
193    */
194   UInt_t Specification() const { return fSpecification; }
195   
196   /**
197    * The copy operator performs a deep copy.
198    * \param domain  The domain entry to copy from.
199    */
200   AliHLTDomainEntry& operator = (const AliHLTDomainEntry& domain);
201   
202   /**
203    * The comparison operator checks to see if two domain entries match.
204    * \param rhs  The right hand side domain entry to compare to.
205    * \return  true if the domain entries are identical or if they overlap (match)
206    *    due to wild card values. False is returned if there is absolutely no
207    *    overlap between this and the right hand side domain entries.
208    * \note No comparison is done for the exclude flag.
209    */
210   bool operator == (const AliHLTDomainEntry& rhs) const
211   {
212     return (fType == rhs.fType) && (fUseSpec && rhs.fUseSpec ? fSpecification == rhs.fSpecification : true);
213   }
214   
215   /**
216    * The comparison operator checks to see if two domain entries do not match.
217    * \param rhs  The right hand side domain entry to compare to.
218    * \return  true if the domain entries do not overlap (match) in any way, also
219    *    after considering any wild card values. False is returned if the entries
220    *    are identical or if they overlap due to wild card values.
221    * \note No comparison is done for the exclude flag.
222    */
223   bool operator != (const AliHLTDomainEntry& rhs) const
224   {
225     return ! this->operator == (rhs);
226   }
227   
228   /**
229    * The comparison operator checks to see if the data block matches the domain entry.
230    * \note The data block's specification is treated as exact and never as a wild card
231    *    'any' value. To be able to treat the specification as 'any', create a new
232    *    AliHLTDomainEntry object with the
233    *      \code AliHLTDomainEntry(const AliHLTComponentDataType& type) \endcode
234    *    constructor, using the data blocks type for the <i>type</i> parameter.
235    *    With the new AliHLTDomainEntry object one can make the required wild card comparison.
236    * \param block  The data block to compare to.
237    * \return  true if the data block matches the domain entry and false otherwise.
238    */
239   bool operator == (const AliHLTComponentBlockData* block) const
240   {
241     return (fType == block->fDataType) && (fUseSpec ? fSpecification == block->fSpecification : true);
242   }
243   
244   /**
245    * The comparison operator checks to see if the data block does not match the domain entry.
246    * \note The data block's specification is treated as exact and never as a wild card
247    *    'any' value. To be able to make the required comparison treating the specification
248    *    as 'any' try the following code:
249    *    \code
250    *      AliHLTComponentBlockData* block;  // assumed initialised.
251    *      AliHLTDomainEntry entryToCompareTo;  // assumed initialised.
252    *      AliHLTDomainEntry newEntryForBlock(block->fDataType);
253    *      bool comparisonResult = (entryToCompareTo == newEntryForBlock);
254    *    \endcode
255    * \param block  The data block to compare to.
256    * \return  true if the data block matches the domain entry and false otherwise.
257    */
258   bool operator != (const AliHLTComponentBlockData* block) const
259   {
260     return ! this->operator == (block);
261   }
262   
263   /**
264    * This typecast operator returns the data type of the domain entry.
265    * \return  Copy of the data block type structure.
266    */
267   operator AliHLTComponentDataType () const { return fType; }
268   
269   /**
270    * Compares this domain entry to another to see if they are identical.
271    * \param rhs  The domain entry to compare to.
272    * \return  True if the two domain entries have the same data types, origins and
273    *   specifications, character for character, ignoring wild card symantics.
274    *   False is returned otherwise.
275    * \note No comparison is done for the exclude flag.
276    */
277   bool IdenticalTo(const AliHLTDomainEntry& rhs) const;
278   
279   /**
280    * Compares this domain entry is a subset of the given entry.
281    * If we consider the possibility of wild card characters, then the domain entry
282    * can be thought of as a set of possible data block entries. This operator
283    * therefore effectively implements set logic.
284    * \param rhs  The domain entry to compare to.
285    * \return  True if the this domain entry is either identical to <i>rhs</i>, i.e.
286    *   IdenticalTo(rhs) returns true, or if <i>rhs</i> can match to all data blocks
287    *   that this domain entry can match to, but also <i>rhs</i> can match to other
288    *   data blocks that this entry cannot match to.
289    * \note No comparison is done for the exclude flag.
290    */
291   bool SubsetOf(const AliHLTDomainEntry& rhs) const;
292   
293   /**
294    * Finds the set intersection between this domain entry and 'rhs', and puts the
295    * intersection value into 'result'.
296    * If we consider the possibility of wild card characters, then the domain entry
297    * can be thought of as a set of possible data block entries. This operator
298    * therefore effectively implements the set intersection.
299    * \param [in]  rhs     The domain entry to compare to.
300    * \param [out] result  The resulting intersect is written into this
301    *    variable if this method returns true. The contents is not modified if
302    *    there is no intersect and this method returns false.
303    * \return true is returned if there is a intersect between the domain entries
304    *    and false otherwise.
305    */
306   bool IntersectWith(const AliHLTDomainEntry& rhs, AliHLTDomainEntry& result) const;
307   
308   /**
309    * Inherited from TObject. Prints the domain entry in the following format:<br>
310    *  \<type\>:\<origin\>:\<specification\><br>
311    * where<br>
312    *  \<type\> is the 8 character data block type.<br>
313    *  \<origin\> is the 4 character data block origin.<br>
314    *  \<specification\> is the data block specification printed in hexadecimal format.<br>
315    * The "\0" string is printed for NULL characters in the type and origin strings.
316    * While "********" is printed for the 'any' data type wild card value, "****"
317    * is printed for the 'any' origin wild card value and "**********" is printed
318    * for the 'any' specification wild card.
319    * \param option  If set to "noendl" then no end of line is printed.
320    */
321   virtual void Print(Option_t* option = "") const;
322   
323   /**
324    * Converts the domain entry type, origin and specification into a string
325    * representation.
326    * \returns  A string in the format \<type\>:\<origin\>:\<specification\>
327    */
328   TString AsString() const;
329
330   /**
331    * Converts the three parameters into a 32 byte buffer
332    * As the PubSub expects the data type id and origin in reverse byte order
333    * those two are swapped. 
334    */
335   int AsBinary(AliHLTUInt32_t buffer[4]) const;
336
337  private:
338   
339   Bool_t fExclude;  /// Indicates if the domain entry is exclusive, indicating data blocks that should not be readout.
340   Bool_t fUseSpec;  /// Indicates if the fSpecification field should be used. If not set then the specification is treated as an 'any' wild card value.
341   AliHLTComponentDataType fType;  /// The HLT data block type.
342   UInt_t fSpecification;  /// The data block specification to match.
343   
344   ClassDef(AliHLTDomainEntry, 1) // A data block type and possible specification entry, which forms part of a trigger domain.
345 };
346
347 #endif // ALIHLTDOMAINENTRY_H
348