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