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    */
 209   bool operator == (const AliHLTDomainEntry& rhs) const
 210   {
 211     return (fType == rhs.fType) && (fUseSpec && rhs.fUseSpec ? fSpecification == rhs.fSpecification : true);
 212   }
 213
 214   /**
 215    * The comparison operator checks to see if two domain entries do not match.
 216    * \param rhs  The right hand side domain entry to compare to.
 217    * \return  true if the domain entries do not overlap (match) in any way, also
 218    *    after considering any wild card values. False is returned if the entries
 219    *    are identical or if they overlap due to wild card values.
 220    */
 221   bool operator != (const AliHLTDomainEntry& rhs) const
 222   {
 223     return ! this->operator == (rhs);
 224   }
 225
 226   /**
 227    * The comparison operator checks to see if the data block matches the domain entry.
 228    * \note The data block's specification is treated as exact and never as a wild card
 229    *    'any' value. To be able to treat the specification as 'any', create a new
 230    *    AliHLTDomainEntry object with the
 231    *      \code AliHLTDomainEntry(const AliHLTComponentDataType& type) \endcode
 232    *    constructor, using the data blocks type for the <i>type</i> parameter.
 233    *    With the new AliHLTDomainEntry object one can make the required wild card comparison.
 234    * \param block  The data block to compare to.
 235    * \return  true if the data block matches the domain entry and false otherwise.
 236    */
 237   bool operator == (const AliHLTComponentBlockData* block) const
 238   {
 239     return (fType == block->fDataType) && (fUseSpec ? fSpecification == block->fSpecification : true);
 240   }
 241
 242   /**
 243    * The comparison operator checks to see if the data block does not match the domain entry.
 244    * \note The data block's specification is treated as exact and never as a wild card
 245    *    'any' value. To be able to make the required comparison treating the specification
 246    *    as 'any' try the following code:
 247    *    \code
 248    *      AliHLTComponentBlockData* block;  // assumed initialised.
 249    *      AliHLTDomainEntry entryToCompareTo;  // assumed initialised.
 250    *      AliHLTDomainEntry newEntryForBlock(block->fDataType);
 251    *      bool comparisonResult = (entryToCompareTo == newEntryForBlock);
 252    *    \endcode
 253    * \param block  The data block to compare to.
 254    * \return  true if the data block matches the domain entry and false otherwise.
 255    */
 256   bool operator != (const AliHLTComponentBlockData* block) const
 257   {
 258     return ! this->operator == (block);
 259   }
 260
 261   /**
 262    * This typecast operator returns the data type of the domain entry.
 263    * \return  Copy of the data block type structure.
 264    */
 265   operator AliHLTComponentDataType () const { return fType; }
 266
 267   /**
 268    * Compares this domain entry to another to see if they are identical.
 269    * \param rhs  The domain entry to compare to.
 270    * \return  True if the two domain entries have the same data types, origins and
 271    *   specifications, character for character, ignoring wild card symantics.
 272    *   False is returned otherwise.
 273    * \note No comparison is done for the exclude flag.
 274    */
 275   bool IdenticalTo(const AliHLTDomainEntry& rhs) const;
 276
 277   /**
 278    * Compares this domain entry is a subset of the given entry.
 279    * If we consider the possibility of wild card characters, then the domain entry
 280    * can be thought of as a set of possible data block entries. This operator
 281    * therefore effectively implements set logic.
 282    * \param rhs  The domain entry to compare to.
 283    * \return  True if the this domain entry is either identical to <i>rhs</i>, i.e.
 284    *   IdenticalTo(rhs) returns true, or if <i>rhs</i> can match to all data blocks
 285    *   that this domain entry can match to, but also <i>rhs</i> can match to other
 286    *   data blocks that this entry cannot match to.
 287    * \note No comparison is done for the exclude flag.
 288    */
 289   bool SubsetOf(const AliHLTDomainEntry& rhs) const;
 290
 291   /**
 292    * Finds the set intersection between this domain entry and 'rhs', and puts the
 293    * intersection value into 'result'.
 294    * If we consider the possibility of wild card characters, then the domain entry
 295    * can be thought of as a set of possible data block entries. This operator
 296    * therefore effectively implements the set intersection.
 297    * \param rhs <i>[in]</i> The domain entry to compare to.
 298    * \param result <i>[out]</i>  The resulting intersect is written into this
 299    *    variable if this method returns true. The contents is not modified if
 300    *    there is no intersect and this method returns false.
 301    * \return true is returned if there is a intersect between the domain entries
 302    *    and false otherwise.
 303    */
 304   bool IntersectWith(const AliHLTDomainEntry& rhs, AliHLTDomainEntry& result) const;
 305
 306   /**
 307    * Inherited from TObject. Prints the domain entry in the following format:<br>
 308    *  \<type\>:\<origin\>:\<specification\><br>
 309    * where<br>
 310    *  \<type\> is the 8 character data block type.<br>
 311    *  \<origin\> is the 4 character data block origin.<br>
 312    *  \<specification\> is the data block specification printed in hexadecimal format.<br>
 313    * The "\0" string is printed for NULL characters in the type and origin strings.
 314    * While "********" is printed for the 'any' data type wild card value, "****"
 315    * is printed for the 'any' origin wild card value and "**********" is printed
 316    * for the 'any' specification wild card.
 317    * \param option  If set to "noendl" then no end of line is printed.
 318    */
 319   virtual void Print(Option_t* option = "") const;
 320
 321   /**
 322    * Converts the domain entry type, origin and specification into a string
 323    * representation.
 324    * \returns  A string in the format \<type\>:\<origin\>:\<specification\>
 325    */
 326   TString AsString() const;
 327
 328   /**
 329    * Converts the three parameters into a 32 byte buffer
 330    * As the PubSub expects the data type id and origin in reverse byte order
 331    * those two are swapped.
 332    */
 333   int AsBinary(AliHLTUInt32_t buffer[4]) const;
 334
 335  private:
 336
 337   Bool_t fExclude;  /// Indicates if the domain entry is exclusive, indicating data blocks that should not be readout.
 338   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.
 339   AliHLTComponentDataType fType;  /// The HLT data block type.
 340   UInt_t fSpecification;  /// The data block specification to match.
 341
 342   ClassDef(AliHLTDomainEntry, 1) // A data block type and possible specification entry, which forms part of a trigger domain.
 343 };
 344
 345 #endif // ALIHLTDOMAINENTRY_H
 346