HLT/BASE/AliHLTDomainEntry.h

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