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