HLT/trigger/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 performs the same operation as the '|=' operator.
 314    * \param domain  The domain object on the right hand side of the operator.
 315    * \return  A reference to this object.
 316    */
 317   AliHLTTriggerDomain& operator += (const AliHLTTriggerDomain& domain)
 318   {
 319     return operator |= (domain);
 320   }
 321
 322   /**
 323    * This operator removes all domain entries from this trigger domain that exisit
 324    * in <i>domain</i>, effectively implementing a set difference.
 325    * \param domain  The domain object on the right hand side of the operator.
 326    * \return  A reference to this object.
 327    */
 328   AliHLTTriggerDomain& operator -= (const AliHLTTriggerDomain& domain);
 329
 330   /**
 331    * This operator returns the set complement of the trigger domain.
 332    * \return  The complement of this trigger domain, such that any data block that
 333    *    returns true for AliHLTTriggerDomain::IncludeInReadout() for this trigger
 334    *    domain, will return false for the same method call in the returned object.
 335    */
 336   AliHLTTriggerDomain operator ~ () const;
 337
 338   /**
 339    * This operator performs a set union between this trigger domain and <i>domain</i>.
 340    * \param domain  The domain object on the right hand side of the operator.
 341    * \return  a trigger domain object R, such that for each data block D, we will have
 342    *    R.IncludeInReadout(D) == this->IncludeInReadout(D) or domain.IncludeInReadout(D)
 343    */
 344   AliHLTTriggerDomain operator | (const AliHLTTriggerDomain& domain) const
 345   {
 346     AliHLTTriggerDomain result = *this;
 347     return result.operator |= (domain);
 348   }
 349
 350   /**
 351    * This operator performs an exclusive or (xor) like operation between this trigger
 352    * domain and <i>domain</i>.
 353    * \param domain  The domain object on the right hand side of the operator.
 354    * \return  a trigger domain object R, such that for each data block D, we will have
 355    *    R.IncludeInReadout(D) == this->IncludeInReadout(D) xor domain.IncludeInReadout(D)
 356    */
 357   AliHLTTriggerDomain operator ^ (const AliHLTTriggerDomain& domain) const
 358   {
 359     AliHLTTriggerDomain result = *this;
 360     return result.operator ^= (domain);
 361   }
 362
 363   /**
 364    * This operator performs a set intersect operation between this trigger domain
 365    * and <i>domain</i>.
 366    * \param domain  The domain object on the right hand side of the operator.
 367    * \return  a trigger domain object R, such that for each data block D, we will have
 368    *    R.IncludeInReadout(D) == this->IncludeInReadout(D) and domain.IncludeInReadout(D)
 369    */
 370   AliHLTTriggerDomain operator & (const AliHLTTriggerDomain& domain) const;
 371
 372   /**
 373    * This operator performs the same operation as the '|' operator.
 374    * \param domain  The domain object on the right hand side of the operator.
 375    * \return  a trigger domain object R, such that for each data block D, we will have
 376    *    R.IncludeInReadout(D) == this->IncludeInReadout(D) or domain.IncludeInReadout(D)
 377    */
 378   AliHLTTriggerDomain operator + (const AliHLTTriggerDomain& domain) const
 379   {
 380     AliHLTTriggerDomain result = *this;
 381     return result.operator += (domain);
 382   }
 383
 384   /**
 385    * This operator implements the set difference between this trigger domain and
 386    * <i>domain</i>.
 387    * \param domain  The domain object on the right hand side of the operator.
 388    * \return  a trigger domain object R, such that for each data block D, we will have
 389    *    R.IncludeInReadout(D) == this->IncludeInReadout(D) and not domain.IncludeInReadout(D)
 390    */
 391   AliHLTTriggerDomain operator - (const AliHLTTriggerDomain& domain) const
 392   {
 393     AliHLTTriggerDomain result = *this;
 394     return result.operator -= (domain);
 395   }
 396
 397   /**
 398    * Typecase operator to create a DDL readout list object from the trigger domain.
 399    */
 400   operator AliHLTReadoutList () const;
 401
 402  private:
 403
 404   /**
 405    * This method merges the domain entries from <i>domain</i> by copying them into
 406    * fEntries, but only the ones not marked for removal in <i>removeDomainEntry</i>.
 407    * Any entries that were marked for removal in fEntries are also removed.
 408    * \param removeThisEntry  Flags which indicate if the corresponding fEntries[i]
 409    *    should be removed.
 410    * \param entriesCount The number of entries in <i>removeThisEntry</i>.
 411    * \param removeDomainEntry  Flags which indicate if the corresponding domain.fEntries[i]
 412    *    was marked for removal or not. If marked for removal then it will not be copied
 413    *    into this trigger domain. The size of the array is given by domain.GetEntriesFast().
 414    * \param startOfIntersects  This is the start location of the new intersection domain
 415    *    entries that were added to fEntries. i.e. fEntries[startOfIntersects] is the
 416    *    first new intersect entry.
 417    */
 418   void MergeEntries(
 419       const bool* removeThisEntry, Int_t entriesCount,
 420       const bool* removeDomainEntry, Int_t startOfIntersects,
 421       const AliHLTTriggerDomain& domain
 422     );
 423
 424   /**
 425    * Goes throught the list of domain entries in fEntries from the first entry
 426    * indicated by 'min' to the end of the list and marks for deletion all entries
 427    * in fEntries that are subsets of 'entry'.
 428    * The entries are marked by setting the 14'th bit in fBits with a call to
 429    * AliHLTDomainEntry::SetBit(14, true).
 430    * \param entry  The entry that should be the super set of the entries we mark
 431    *    for removal.
 432    * \param min  This is the first entry we consider, all the way up to
 433    *    fEntries.GetEntriesFast() - 1.
 434    */
 435   void MarkForDeletionSubsetsOf(const AliHLTDomainEntry& entry, Int_t min);
 436
 437   /**
 438    * Removes all entries in this trigger domain which were marked for removal.
 439    * These are all domain entries that have the 14'th bit set in their fBits field
 440    * with a call to AliHLTDomainEntry::SetBit(14, true).
 441    */
 442   void RemoveMarkedEntries();
 443
 444   /**
 445    * Removes any redundant trigger domain entries from the fEntries list.
 446    * Entries that are subsets of each other are removed. Also exclusive entries
 447    * that are not subsets of any inclusive entry are also removed, because we
 448    * implicitly assume a data block does not form part of the trigger domain,
 449    * unless explicitly included with an inclusive domain entry. So these kinds
 450    * of entries are redundant.
 451    */
 452   void Optimise();
 453
 454   TClonesArray fEntries;  /// The list of domain entries used to decide if a data block forms part of trigger domain set.
 455
 456   ClassDef(AliHLTTriggerDomain, 1) // This is a list of internal HLT data block types which should be forwarded for readout.
 457
 458 };
 459
 460 #endif // ALIHLTTRIGGERDOMAIN_H
 461