moving trigger description classes to HLTbase to make them commonly available
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTTriggerDomain.h
1 #ifndef ALIHLTTRIGGERDOMAIN_H
2 #define ALIHLTTRIGGERDOMAIN_H
3 /* This file is property of and copyright by the ALICE HLT Project        *
4  * ALICE Experiment at CERN, All rights reserved.                         *
5  * See cxx source for full Copyright notice                               */
6
7 /// @file   AliHLTDomainEntry.h
8 /// @author Artur Szostak <artursz@iafrica.com>
9 /// @date   19 Nov 2008
10 /// @brief  Declaration of the AliHLTTriggerDomain class used to store the set of data block types to readout.
11
12 #include "TObject.h"
13 #include "TClonesArray.h"
14 #include "AliHLTDataTypes.h"
15
16 class AliHLTDomainEntry;
17 class AliHLTReadoutList;
18
19 /**
20  * \class AliHLTTriggerDomain
21  * The trigger domain class is the set of HLT raw data block types that should
22  * be readout and sent to HLTOUT.
23  * It is implemented as a list of domain entries, where each domain entry is
24  * like a rule, or pattern to match against. When trying to decide if a given
25  * data block falls within the trigger domain, i.e. is part of the readout, the
26  * domain entries are applied one after the other from top to bottom. Two kinds
27  * of domain entries, inclusive and exclusive are possible, which indicate if a
28  * data block type or range, is part of the trigger domain or not. As we process
29  * the domain entries we update our decision of whether the data block is part
30  * of the trigger domain or not. If the domain entry is an inclusion then we update
31  * the decision to true, if it is an exclusion then we update the decision to false.
32  * The value of the result after applying the last domain entry then indicates
33  * if the data block is part of the trigger domain or not.
34  * In this way we can specify trigger domains as sets to arbitrary complexity
35  * and manipulate them as mathematical sets accordingly.
36  *
37  * The other feature of the AliHLTTriggerDomain class is that it overloads the
38  * following operators to provide set like behaviour:
39  *   |  this provides the set union operation (The + operator does the same).
40  *   &  this provides the set intersect operation.
41  *   -  this provides the set difference operation.
42  *   ^  this provides an exclusive or (xor) operation. i.e. given two sets A and B
43  *        the result C is given by:
44  *        C = {x : x elf A and not x elf B, or x elf B and not x elf A}
45  *        where 'elf' means "is an element of".
46  *   ~  this returns the set complement.
47  * These operators then allow expressions to be formed from trigger domain objects
48  * which behave like sets.
49  */
50 class AliHLTTriggerDomain : public TObject
51 {
52  public:
53   
54   /**
55    * Default constructor.
56    */
57   AliHLTTriggerDomain();
58   
59   /**
60    * Constructs the trigger domain from a list of domain entries.
61    * \param list  Comma separated list of domain entries of the form xxx:yyy:zzz
62    *    Can optionaly have a '+' or '-' character just in front of the block
63    *    type string, xxx in this case, to indicate inclusive or exclusive entries.
64    * \note If inclusive and exclusive entries are specified then they are applied
65    *    in the order found in the list, from left to right. This means that subsequent
66    *    includes can override previous excludes and visa versa.
67    */
68   AliHLTTriggerDomain(const char* list);
69   
70   /**
71    * Constructor to create a trigger domain from a DDL readout list.
72    * The trigger domain will contain entries of the form "DAQRDOUT:xxxx:yyyy"
73    * where xxxx is the appropriate detector name given by AliDAQ::OnlineName()
74    * and yyyy is the DDL equipment ID number.
75    * \param list  The read out list object
76    */
77   AliHLTTriggerDomain(const AliHLTReadoutList& list);
78   
79   /**
80    * Copy constructor performs a deep copy.
81    * \param domain  The domain entry to copy from.
82    */
83   AliHLTTriggerDomain(const AliHLTTriggerDomain& domain);
84   
85   /**
86    * Default destructor.
87    */
88   virtual ~AliHLTTriggerDomain();
89   
90   /**
91    * Adds entries to the trigger domain to correspond to the DDL readout list.
92    * The trigger domain will contain entries of the form "DAQRDOUT:xxxx:yyyy"
93    * where xxxx is the appropriate detector name given by AliDAQ::OnlineName()
94    * and yyyy is the DDL equipment ID number.
95    * \param list  The readout list object
96    */
97   void Add(const AliHLTReadoutList& list);
98   
99   /**
100    * Adds the given entry to this trigger domain as an inclusive entry.
101    * Existing entries are modified as required to optimise the trigger domain
102    * rule / pattern matching list.
103    * \param entry  The domain entry object to add.
104    * \note The entry.Exclusive() flag is ignored and is treated as if it was kFALSE.
105    */
106   void Add(const AliHLTDomainEntry& entry);
107   
108   /**
109    * Adds the given data type to the trigger domain such that all data blocks
110    * that match this type will form part of the trigger domain.
111    * \param datatype  The data block type and origin to match.
112    */
113   void Add(const AliHLTComponentDataType& datatype);
114   
115   /**
116    * Adds the given data type and origin to the trigger domain such that all data
117    * blocks that match will form part of this trigger domain.
118    * \param blocktype  The data block type string of the data block that must match.
119    *    The value of kAliHLTAnyDataTypeID can be used to specify the 'any' type
120    *    wild card value.
121    * \param origin  The origin of the data block, such as the detector name, that
122    *    must match. The value of kAliHLTDataOriginAny can be used to specify the
123    *    'any' origin wild card value.
124    */
125   void Add(const char* blocktype, const char* origin);
126   
127   /**
128    * Adds the given data type with particular specification bits to the trigger
129    * domain, such that all data blocks that match these will form part of this
130    * trigger domain.
131    * \param datatype  The data block type and origin that must match.
132    * \param spec  The specification bits that must match.
133    */
134   void Add(const AliHLTComponentDataType& datatype, UInt_t spec);
135   
136   /**
137    * Adds the given data type, origin and specification bits of data blocks that
138    * should form part of this trigger domain.
139    * \param blocktype  The data block type string of the data block that must match.
140    *    The value of kAliHLTAnyDataTypeID can be used to specify the 'any' type
141    *    wild card value.
142    * \param origin  The origin of the data block, such as the detector name, that
143    *    must match. The value of kAliHLTDataOriginAny can be used to specify the
144    *    'any' origin wild card value.
145    * \param spec  The specification bits that must match.
146    */
147   void Add(const char* blocktype, const char* origin, UInt_t spec);
148   
149   /**
150    * Removes entries from the trigger domain that correspond to the DDL readout list.
151    * All entries of the form "DAQRDOUT:xxxx:yyyy" are removed, where xxxx is the
152    * appropriate detector name given by AliDAQ::OnlineName() and yyyy is the DDL
153    * equipment ID number, as long as the corresponding bit is set in the readout
154    * list.
155    * \param list  The readout list object
156    */
157   void Remove(const AliHLTReadoutList& list);
158   
159   /**
160    * Removes or modifies all entries from the trigger domain, such that data blocks
161    * that match the given domain entry will not form part of this trigger domain.
162    * Existing entries are modified as required to optimise the trigger domain
163    * rule / pattern matching list.
164    * \param entry  The domain entry object to indicating values that should be removed.
165    * \note The entry.Exclusive() flag is ignored and is treated as if it was kTRUE.
166    */
167   void Remove(const AliHLTDomainEntry& entry);
168   
169   /**
170    * Removes the given data type from the trigger domain, such that all data blocks
171    * that match this type will not form part of the trigger domain.
172    * \param datatype  The data block type and origin that must match the blocks not
173    *    forming part of this trigger domain.
174    */
175   void Remove(const AliHLTComponentDataType& datatype);
176   
177   /**
178    * Removes the given data type and origin from the trigger domain, such that all
179    * data blocks that match these will not form part of the trigger domain.
180    * \param blocktype  The data block type string that must match the data blocks
181    *    not forming part of this trigger domain.
182    *    The value of kAliHLTAnyDataTypeID can be used to specify the 'any' type
183    *    wild card value.
184    * \param origin  The origin string, such as the detector name, that must match
185    *    the data blocks not forming part of this trigger domain.
186    *    The value of kAliHLTDataOriginAny can be used to specify the 'any' origin
187    *    wild card value.
188    */
189   void Remove(const char* blocktype, const char* origin);
190   
191   /**
192    * Removes the given data type with given specification bit from the trigger
193    * domain, such that all data blocks that match these will not form part of the
194    * trigger domain.
195    * \param datatype  The data block type and origin that must match the blocks
196    *    not forming part of this trigger domain.
197    * \param spec  The specification bits that must match for the blocks that do
198    *    not form part of this trigger domain.
199    */
200   void Remove(const AliHLTComponentDataType& datatype, UInt_t spec);
201   
202   /**
203    * Removes the given data type, origin and specification from the trigger domain,
204    * such that all data blocks that match these will not form part of the trigger
205    * domain.
206    * \param blocktype  The data block type string that must match the data blocks
207    *    not forming part of this trigger domain.
208    *    The value of kAliHLTAnyDataTypeID can be used to specify the 'any' type
209    *    wild card value.
210    * \param origin  The origin string, such as the detector name, that must match
211    *    the data blocks not forming part of this trigger domain.
212    *    The value of kAliHLTDataOriginAny can be used to specify the 'any' origin
213    *    wild card value.
214    * \param spec  The specification bits that must match for the blocks that do
215    *    not form part of this trigger domain.
216    */
217   void Remove(const char* blocktype, const char* origin, UInt_t spec);
218   
219   /**
220    * This checks to see if the given entry (or class of entries, if the entry uses
221    * wild card values) is part of the trigger domain.
222    * \param entry  This is the entry to check for.
223    * \return  true if data blocks that match the entry are part of this
224    *    trigger domain and false otherwise.
225    * \note If the block contains the 'any' wild card values for the data type
226    *    origin or specification, then the inclusive domains are treated
227    *    optimistically and the exclusive domains pessimistically. This means that
228    *    the wild card values are assumed to fall within the trigger domain for the
229    *    optimistic case, but fall outside the domain for the pessimistic case.
230    */
231   bool Contains(const AliHLTDomainEntry& entry) const;
232   
233   /**
234    * This checks to see if the given data block should be included in the HLT readout.
235    * \param block  The data block descriptor to check.
236    * \return  true if data block forms part of this trigger domain and should
237    *    be part of the readout and false otherwise.
238    * \note If the block contains the 'any' wild card values for the data type
239    *    or origin, then the inclusive domains are treated optimistically and the
240    *    exclusive domains pessimistically. This means that the wild card values
241    *    are assumed to fall within the trigger domain for the optimistic case,
242    *    but fall outside the domain for the pessimistic case.
243    */
244   bool IncludeInReadout(const AliHLTComponentBlockData* block) const;
245   
246   /**
247    * This checks to see if the given data block should not be included in the
248    * HLT readout.
249    * \param block  The data block descriptor to check.
250    * \return  true if data block does not form part of this trigger domain and
251    *    false otherwise.
252    */
253   bool ExcludeFromReadout(const AliHLTComponentBlockData* block) const
254   {
255     return ! IncludeInReadout(block);
256   }
257   
258   /**
259    * This method removes all entries in the trigger domain list, giving us and
260    * empty trigger domain set.
261    * \param  option  This is passed onto the internal fEntries TClonesArray.
262    * The method is inherited from TObject.
263    */
264   virtual void Clear(Option_t* option = "");
265   
266   /**
267    * Prints all the domain entries in this trigger domain in the order in which
268    * they are applied and if they are inclusive or exclusive.
269    * \param  option  This is not used by this method.
270    * The method is inherited from TObject.
271    */
272   virtual void Print(Option_t* option = "") const;
273
274   /**
275    * Assignment operator performs a deep copy.
276    * \param domain  The domain entry to copy from.
277    * \return  A reference to this object.
278    */
279   AliHLTTriggerDomain& operator = (const AliHLTTriggerDomain& domain);
280   
281   /**
282    * This operator adds all domain entries in <i>domain</i> to this trigger domain
283    * in such a way, so as to effectively perform a set union.
284    * \param domain  The domain object on the right hand side of the operator.
285    * \return  A reference to this object.
286    */
287   AliHLTTriggerDomain& operator |= (const AliHLTTriggerDomain& domain);
288   
289   /**
290    * This operator adds all domain entries in <i>domain</i> that do not exist in
291    * this trigger domain, but removes all entries that do exist, effectively
292    * performing an exclusive or (xor) operation.
293    * i.e. given two sets A and B the result C is given by:
294    *    C = {x : x elf A and not x elf B, or x elf B and not x elf A}
295    * where 'elf' means "is an element of".
296    * \param domain  The domain object on the right hand side of the operator.
297    * \return  A reference to this object.
298    */
299   AliHLTTriggerDomain& operator ^= (const AliHLTTriggerDomain& domain);
300   
301   /**
302    * This operator removes all domain entries from this trigger domain that do
303    * not also exist in <i>domain</i>, effectively performing a set intersect.
304    * \param domain  The domain object on the right hand side of the operator.
305    * \return  A reference to this object.
306    */
307   AliHLTTriggerDomain& operator &= (const AliHLTTriggerDomain& domain)
308   {
309     return this->operator = (*this & domain);
310   }
311   
312   /**
313    * This operator removes all domain entries from this trigger domain that exisit
314    * in <i>domain</i>, effectively implementing a set difference.
315    * \param domain  The domain object on the right hand side of the operator.
316    * \return  A reference to this object.
317    */
318   AliHLTTriggerDomain& operator -= (const AliHLTTriggerDomain& domain);
319   
320   /**
321    * This operator returns the set complement of the trigger domain.
322    * \return  The complement of this trigger domain, such that any data block that
323    *    returns true for AliHLTTriggerDomain::IncludeInReadout() for this trigger
324    *    domain, will return false for the same method call in the returned object.
325    */
326   AliHLTTriggerDomain operator ~ () const;
327   
328   /**
329    * This operator performs a set union between this trigger domain and <i>domain</i>.
330    * \param domain  The domain object on the right hand side of the operator.
331    * \return  a trigger domain object R, such that for each data block D, we will have
332    *    R.IncludeInReadout(D) == this->IncludeInReadout(D) or domain.IncludeInReadout(D)
333    */
334   AliHLTTriggerDomain operator | (const AliHLTTriggerDomain& domain) const
335   {
336     AliHLTTriggerDomain result = *this;
337     return result.operator |= (domain);
338   }
339   
340   /**
341    * This operator performs an exclusive or (xor) like operation between this trigger
342    * domain and <i>domain</i>.
343    * \param domain  The domain object on the right hand side of the operator.
344    * \return  a trigger domain object R, such that for each data block D, we will have
345    *    R.IncludeInReadout(D) == this->IncludeInReadout(D) xor domain.IncludeInReadout(D)
346    */
347   AliHLTTriggerDomain operator ^ (const AliHLTTriggerDomain& domain) const
348   {
349     AliHLTTriggerDomain result = *this;
350     return result.operator ^= (domain);
351   }
352   
353   /**
354    * This operator performs a set intersect operation between this trigger domain
355    * and <i>domain</i>.
356    * \param domain  The domain object on the right hand side of the operator.
357    * \return  a trigger domain object R, such that for each data block D, we will have
358    *    R.IncludeInReadout(D) == this->IncludeInReadout(D) and domain.IncludeInReadout(D)
359    */
360   AliHLTTriggerDomain operator & (const AliHLTTriggerDomain& domain) const;
361   
362   /**
363    * This operator implements the set difference between this trigger domain and
364    * <i>domain</i>.
365    * \param domain  The domain object on the right hand side of the operator.
366    * \return  a trigger domain object R, such that for each data block D, we will have
367    *    R.IncludeInReadout(D) == this->IncludeInReadout(D) and not domain.IncludeInReadout(D)
368    */
369   AliHLTTriggerDomain operator - (const AliHLTTriggerDomain& domain) const
370   {
371     AliHLTTriggerDomain result = *this;
372     return result.operator -= (domain);
373   }
374   
375   /**
376    * Typecase operator to create a DDL readout list object from the trigger domain.
377    */
378   operator AliHLTReadoutList () const;
379   
380  private:
381   
382   /**
383    * This method merges the domain entries from <i>domain</i> by copying them into
384    * fEntries, but only the ones not marked for removal in <i>removeDomainEntry</i>.
385    * Any entries that were marked for removal in fEntries are also removed.
386    * \param removeThisEntry  Flags which indicate if the corresponding fEntries[i]
387    *    should be removed.
388    * \param entriesCount The number of entries in <i>removeThisEntry</i>.
389    * \param removeDomainEntry  Flags which indicate if the corresponding domain.fEntries[i]
390    *    was marked for removal or not. If marked for removal then it will not be copied
391    *    into this trigger domain. The size of the array is given by domain.GetEntriesFast().
392    * \param startOfIntersects  This is the start location of the new intersection domain
393    *    entries that were added to fEntries. i.e. fEntries[startOfIntersects] is the
394    *    first new intersect entry.
395    */
396   void MergeEntries(
397       const bool* removeThisEntry, Int_t entriesCount,
398       const bool* removeDomainEntry, Int_t startOfIntersects,
399       const AliHLTTriggerDomain& domain
400     );
401   
402   /**
403    * Goes throught the list of domain entries in fEntries from the first entry
404    * indicated by 'min' to the end of the list and marks for deletion all entries
405    * in fEntries that are subsets of 'entry'.
406    * The entries are marked by setting the 14'th bit in fBits with a call to
407    * AliHLTDomainEntry::SetBit(14, true).
408    * \param entry  The entry that should be the super set of the entries we mark
409    *    for removal.
410    * \param min  This is the first entry we consider, all the way up to
411    *    fEntries.GetEntriesFast() - 1.
412    */
413   void MarkForDeletionSubsetsOf(const AliHLTDomainEntry& entry, Int_t min);
414   
415   /**
416    * Removes all entries in this trigger domain which were marked for removal.
417    * These are all domain entries that have the 14'th bit set in their fBits field
418    * with a call to AliHLTDomainEntry::SetBit(14, true).
419    */
420   void RemoveMarkedEntries();
421   
422   /**
423    * Removes any redundant trigger domain entries from the fEntries list.
424    * Entries that are subsets of each other are removed. Also exclusive entries
425    * that are not subsets of any inclusive entry are also removed, because we
426    * implicitly assume a data block does not form part of the trigger domain,
427    * unless explicitly included with an inclusive domain entry. So these kinds
428    * of entries are redundant.
429    */
430   void Optimise();
431   
432   TClonesArray fEntries;  /// The list of domain entries used to decide if a data block forms part of trigger domain set.
433   
434   ClassDef(AliHLTTriggerDomain, 1) // This is a list of internal HLT data block types which should be forwarded for readout.
435
436 };
437
438 #endif // ALIHLTTRIGGERDOMAIN_H
439