HLT/BASE/AliHLTScalars.h

   1 //-*- Mode: C++ -*-
   2 // $Id$
   3 #ifndef AliHLTSCALARS_H
   4 #define AliHLTSCALARS_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   AliHLTScalars.h
  10 ///  @author Artur Szostak <artursz@iafrica.com>
  11 ///  @date   28 Sep 2010
  12 ///  @brief  Declares the a base class for named scalar values.
  13
  14 #include "TObject.h"
  15 #include "TNamed.h"
  16 #include "TClonesArray.h"
  17 #include "THashTable.h"
  18
  19 /**
  20  * @class AliHLTScalars
  21  * @brief Container for named scalar values.
  22  *
  23  * This class contains a list of named scalars for an event as summary information.
  24  * These can be used by the trigger components to perform event selection or used
  25  * for monitoring purposes.
  26  *
  27  * \ingroup alihlt_base
  28  */
  29 class AliHLTScalars : public TObject
  30 {
  31 public:
  32         /**
  33          * This class stores a single scalar value and name.
  34          */
  35         class AliScalar : public TNamed
  36         {
  37         public:
  38                 /// Default constructor
  39                 AliScalar() : TNamed(), fValue(0) {}
  40
  41                 /// Constructor to set the initial value.
  42                 AliScalar(const char* name, const char* description, Double_t value) :
  43                         TNamed(name, description), fValue(value)
  44                 {}
  45
  46                 /// Default destructor
  47                 virtual ~AliScalar() {}
  48
  49                 /// Inherited from TObject. Compares two scalar names.
  50                 virtual Int_t Compare(const TObject *obj) const
  51                 {
  52                         return fName.CompareTo(obj->GetName());
  53                 }
  54
  55                 /// Inherited from TObject. Returns true.
  56                 virtual Bool_t IsSortable() const { return kTRUE; }
  57
  58                 /**
  59                  * Inherited from TObject.
  60                  * Returns true if the names of the scalars are the same.
  61                  */
  62                 virtual Bool_t IsEqual(const TObject *obj) const
  63                 {
  64                         return fName == obj->GetName();
  65                 }
  66
  67                 /// Resets the scalar value to zero.
  68                 virtual void Clear(Option_t* /*option*/ = "") { fValue = 0; }
  69
  70                 /// Inherited from TObject. Performs a deep copy.
  71                 virtual void Copy(TObject& object) const;
  72
  73                 /// Returns the value of the scalar.
  74                 Double_t Value() const { return fValue; }
  75
  76                 /// Sets a new value for the scalar.
  77                 void Value(Double_t value) { fValue = value; }
  78
  79                 /**
  80                  * Increments the scalar by a value of 'count'.
  81                  * \param count  The number to increment the scalar by. The default is 1.
  82                  */
  83                 void Increment(UInt_t count = 1) { fValue += count; }
  84
  85                 /// Returns the name of the scalar.
  86                 const char* Name() const { return fName.Data(); }
  87
  88                 /// Returns the description string for the scalar.
  89                 const char* Description() const { return fTitle.Data(); }
  90
  91                 /// Checks if two scalar objects are identical.
  92                 bool operator == (const AliScalar& x) const
  93                 {
  94                         return fValue == x.fValue and fName == x.fName and fTitle == x.fTitle;
  95                 }
  96
  97                 /// Checks if two scalar objects are not identical.
  98                 bool operator != (const AliScalar& x) const
  99                 {
 100                         return not (this->operator == (x));
 101                 }
 102
 103                 /// Typecast operator for returning the value directly.
 104                 operator Double_t () const { return fValue; }
 105
 106         private:
 107                 Double_t fValue; // The scalar's value.
 108
 109                 ClassDef(AliScalar, 1);  // HLT scalar value.
 110         };
 111
 112         /// Default constructor.
 113         AliHLTScalars();
 114
 115         /// The copy constructor performs a deep copy.
 116         AliHLTScalars(const AliHLTScalars& obj);
 117
 118         /// Default destructor.
 119         virtual ~AliHLTScalars();
 120
 121         /**
 122          * Adds a new scalar to the end of the scalars list.
 123          * If the scalar already exists then its values are updated instead.
 124          * \param name  The name of the scalar.
 125          * \param description  A short description of the scalar.
 126          * \param value  The value of the new scalar.
 127          * \returns true if the scalar already exists and false otherwise.
 128          */
 129         virtual bool Add(const char* name, const char* description = NULL, Double_t value = 0);
 130
 131         /**
 132          * Removes a named scalar from the scalars list.
 133          * \param name  The name of the scalar to remove.
 134          * \returns true if the scalar existed and false otherwise.
 135          * \note The scalars list is compressed so this method will be slow.
 136          *    In addition, scalar positions will change if not removing from the end.
 137          */
 138         virtual bool Remove(const char* name);
 139
 140         /// Checks to see if the named scalar exists.
 141         bool Exists(const char* name) const { return fMap.FindObject(name) != NULL; }
 142
 143         /**
 144          * Fetches the specified scalar object.
 145          * \param name  The name of the scalar object.
 146          * \returns the found scalar object, otherwise an empty sentinel object with
 147          *    zeros. One can tell it is a sentinel because the name will be empty.
 148          */
 149         const AliScalar& GetScalar(const char* name) const;
 150
 151         /**
 152          * Fetches the specified scalar object for editing.
 153          * \param name  The name of the scalar object.
 154          * \returns the found scalar object. If the scalar does not already
 155          *     exist then a new one is created and returned.
 156          */
 157         AliScalar& GetScalar(const char* name);
 158
 159         /// Returns the number of scalar values.
 160         UInt_t NumberOfScalars() const { return UInt_t(fScalars.GetEntriesFast()); }
 161
 162         // Note: the following GetScalarN methods do not use the same name as
 163         // GetScalar above because the parameter type would unfortunately be
 164         // ambiguous to an ISO c++ compiler.
 165
 166         /**
 167          * Fetches the n'th scalar object.
 168          * \param n  The number of the scalar object.
 169          * \returns the found scalar object, otherwise an empty sentinel object with
 170          *    zeros. One can tell it is a sentinel because the name will be empty.
 171          */
 172         const AliScalar& GetScalarN(UInt_t n) const;
 173
 174         /**
 175          * Fetches the n'th scalar object for editing.
 176          * \param n  The number of the scalar object.
 177          * \returns the found scalar object. If the scalar does not already
 178          *     exist then a new one is created and returned.
 179          */
 180         AliScalar& GetScalarN(UInt_t n);
 181
 182         /// Resets all scalar values to zero.
 183         virtual void Reset();
 184
 185         /**
 186          * Removes all the scalars from the internal array.
 187          * \param option  This is passed onto the internal Delete method.
 188          */
 189         virtual void Clear(Option_t* option = "");
 190
 191         /// Inherited form TObject. Performs a deep copy.
 192         virtual void Copy(TObject& object) const;
 193
 194         /// Finds the scalar object by name.
 195         virtual TObject* FindObject(const char* name) const
 196         {
 197                 return fMap.FindObject(name);
 198         }
 199
 200         /// Finds the scalar object with the same name as obj->GetName().
 201         virtual TObject* FindObject(const TObject* obj) const
 202         {
 203                 return fMap.FindObject(obj->GetName());
 204         }
 205
 206         /**
 207          * Inherited from TObject, this prints the contents of all the scalars.
 208          * \param option  Can be "compact", which will just print all the values on one line.
 209          */
 210         virtual void Print(Option_t* option = "") const;
 211
 212         /**
 213          * The assignment operator performs a deep copy.
 214          */
 215         AliHLTScalars& operator = (const AliHLTScalars& obj);
 216
 217         /// Returns the n'th scalar or a zero sentinel if n is out of range.
 218         const AliScalar& operator [] (UInt_t n) const { return GetScalarN(n); }
 219
 220         /// Returns the n'th scalar for editing. A new scalar is created if n is out of range.
 221         AliScalar& operator [] (UInt_t n) { return GetScalarN(n); }
 222
 223         /// Returns the named scalar or a zero sentinel if no such scalar is found.
 224         const AliScalar& operator [] (const TString& name) const { return GetScalar(name.Data()); }
 225
 226         /// Returns the named scalar for editing. A new scalar is created if the named scalar is not found.
 227         AliScalar& operator [] (const TString& name) { return GetScalar(name.Data()); }
 228
 229         /**
 230          * Inherited from TObject.
 231          * Returns true if the names of the two sets of scalars are the same.
 232          * \note The actual values are not checked. Use the comparison operator for that.
 233          */
 234         virtual Bool_t IsEqual(const TObject *obj) const;
 235
 236         /**
 237          * Comparison operator to check if two sets of scalars have the same values.
 238          * \note The description strings are not checked so they could be different
 239          *   and the order of the scalars does not matter either.
 240          */
 241         bool operator == (const AliHLTScalars& obj) const;
 242
 243         /**
 244          * Comparison operator to check if two sets of scalars are different.
 245          * \note The description strings are not checked, only the values are.
 246          *   In addition, the order of the scalars does not matter.
 247          */
 248         bool operator != (const AliHLTScalars& obj) const
 249         {
 250                 return not (this->operator == (obj));
 251         }
 252
 253 protected:
 254
 255         /**
 256          * Constructor that can be used by deriving classes to overload the class stored
 257          * in the fScalars TClonesArray.
 258          * \param cl  The class to use in the fScalars as passed to the TClonesArray constructor.
 259          * \param initSize  The initial approximate number of elements in fScalars. (Default = 128).
 260          * \note The class used in <i>cl</i> must derive from AliHLTScalars::AliScalar.
 261          */
 262         AliHLTScalars(const TClass* cl, Int_t initSize = 128);
 263
 264         /**
 265          * This method creates a new scalar object in the fScalars TClonesArray.
 266          * \param i  Location of the new object to construct in the TClonesArray.
 267          * \param name  The name of the new scalar.
 268          * \param description  The description of the new scalar.
 269          * \param value  The value of the new scalar.
 270          * \returns the pointer to the new object created.
 271          * \note This method must be overridden by classes inheriting from this class if
 272          *    the protected AliHLTScalars(const TClass*, Int_t) constructor is used to
 273          *    change the class stored in the fScalars TClonesArray.
 274          *    One should use the method ScalarForConstructor to get the location where
 275          *    the new scalar object will be constructed.
 276          */
 277         virtual AliScalar* NewScalar(UInt_t i, const char* name, const char* description, Double_t value);
 278
 279         /**
 280          * Returns a pointer to the memory where a new scalar object should be constructed.
 281          * \param i  The position of the new object.
 282          */
 283         TObject*& ScalarForConstructor(UInt_t i) { return fScalars[Int_t(i)]; }
 284
 285         /**
 286          * This method should return an empty sentinel object to mark that a scalar was
 287          * not found in the list.
 288          * \note This method must be overridden by classes inheriting from this class if
 289          *    the protected AliHLTScalars(const TClass*, Int_t) constructor is used to
 290          *    change the class stored in the fScalars TClonesArray.
 291          */
 292         virtual const AliScalar& Sentinel() const;
 293
 294         /**
 295          * This is an internal Add method which can be faster to use than the public Add method
 296          * directly for classes derived from AliHLTScalars.
 297          * \param [out] scalar This gets filled with the pointer of the new scalar created or
 298          *    the existing one found.
 299          * \param [in] name The name of the scalar.
 300          * \param [in] description  A short description of the scalar.
 301          * \param [in] value  The value of the new scalar.
 302          * \returns true if the scalar already exists and false otherwise.
 303          */
 304         bool Add(AliScalar*& scalar, const char* name, const char* description, Double_t value);
 305
 306         /**
 307          * Utility method for classes deriving from AliHLTScalars to fetch the i'th scalar
 308          * from the TClonesArray without checking that the index is valid.
 309          * \param i  The index number of the scalar to fetch.
 310          */
 311         AliScalar* ScalarUncheckedAt(UInt_t i) const { return static_cast<AliScalar*>(fScalars.UncheckedAt(Int_t(i))); }
 312
 313 private:
 314
 315         TClonesArray fScalars;  // List of scalar objects.
 316         THashTable fMap;        //! Hash table of pointers to the scalars for fast lookup.
 317
 318         ClassDef(AliHLTScalars, 1);  // Set of HLT scalars.
 319 };
 320
 321 #endif // AliHLTSCALARS_H