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   /// Needed by schema evolution
 122   const TClonesArray* GetScalars() const { return &fScalars; }
 123
 124         /**
 125          * Adds a new scalar to the end of the scalars list.
 126          * If the scalar already exists then its values are updated instead.
 127          * \param name  The name of the scalar.
 128          * \param description  A short description of the scalar.
 129          * \param value  The value of the new scalar.
 130          * \returns true if the scalar already exists and false otherwise.
 131          */
 132         virtual bool Add(const char* name, const char* description = NULL, Double_t value = 0);
 133
 134         /**
 135          * Removes a named scalar from the scalars list.
 136          * \param name  The name of the scalar to remove.
 137          * \returns true if the scalar existed and false otherwise.
 138          * \note The scalars list is compressed so this method will be slow.
 139          *    In addition, scalar positions will change if not removing from the end.
 140          */
 141         virtual bool Remove(const char* name);
 142
 143         /// Checks to see if the named scalar exists.
 144         bool Exists(const char* name) const { return fMap.FindObject(name) != NULL; }
 145
 146         /**
 147          * Fetches the specified scalar object.
 148          * \param name  The name of the scalar object.
 149          * \returns the found scalar object, otherwise an empty sentinel object with
 150          *    zeros. One can tell it is a sentinel because the name will be empty.
 151          */
 152         const AliScalar& GetScalar(const char* name) const;
 153
 154         /**
 155          * Fetches the specified scalar object for editing.
 156          * \param name  The name of the scalar object.
 157          * \returns the found scalar object. If the scalar does not already
 158          *     exist then a new one is created and returned.
 159          */
 160         AliScalar& GetScalar(const char* name);
 161
 162         /// Returns the number of scalar values.
 163         UInt_t NumberOfScalars() const { return UInt_t(fScalars.GetEntriesFast()); }
 164
 165         // Note: the following GetScalarN methods do not use the same name as
 166         // GetScalar above because the parameter type would unfortunately be
 167         // ambiguous to an ISO c++ compiler.
 168
 169         /**
 170          * Fetches the n'th scalar object.
 171          * \param n  The number of the scalar object.
 172          * \returns the found scalar object, otherwise an empty sentinel object with
 173          *    zeros. One can tell it is a sentinel because the name will be empty.
 174          */
 175         const AliScalar& GetScalarN(UInt_t n) const;
 176
 177         /**
 178          * Fetches the n'th scalar object for editing.
 179          * \param n  The number of the scalar object.
 180          * \returns the found scalar object. If the scalar does not already
 181          *     exist then a new one is created and returned.
 182          */
 183         AliScalar& GetScalarN(UInt_t n);
 184
 185         /// Resets all scalar values to zero.
 186         virtual void Reset();
 187
 188         /**
 189          * Removes all the scalars from the internal array.
 190          * \param option  This is passed onto the internal Delete method.
 191          */
 192         virtual void Clear(Option_t* option = "");
 193
 194         /// Inherited form TObject. Performs a deep copy.
 195         virtual void Copy(TObject& object) const;
 196
 197         /// Finds the scalar object by name.
 198         virtual TObject* FindObject(const char* name) const
 199         {
 200                 return fMap.FindObject(name);
 201         }
 202
 203         /// Finds the scalar object with the same name as obj->GetName().
 204         virtual TObject* FindObject(const TObject* obj) const
 205         {
 206                 return fMap.FindObject(obj->GetName());
 207         }
 208
 209         /**
 210          * Inherited from TObject, this prints the contents of all the scalars.
 211          * \param option  Can be "compact", which will just print all the values on one line.
 212          */
 213         virtual void Print(Option_t* option = "") const;
 214
 215         /**
 216          * The assignment operator performs a deep copy.
 217          */
 218         AliHLTScalars& operator = (const AliHLTScalars& obj);
 219
 220         /// Returns the n'th scalar or a zero sentinel if n is out of range.
 221         const AliScalar& operator [] (UInt_t n) const { return GetScalarN(n); }
 222
 223         /// Returns the n'th scalar for editing. A new scalar is created if n is out of range.
 224         AliScalar& operator [] (UInt_t n) { return GetScalarN(n); }
 225
 226         /// Returns the named scalar or a zero sentinel if no such scalar is found.
 227         const AliScalar& operator [] (const TString& name) const { return GetScalar(name.Data()); }
 228
 229         /// Returns the named scalar for editing. A new scalar is created if the named scalar is not found.
 230         AliScalar& operator [] (const TString& name) { return GetScalar(name.Data()); }
 231
 232         /**
 233          * Inherited from TObject.
 234          * Returns true if the names of the two sets of scalars are the same.
 235          * \note The actual values are not checked. Use the comparison operator for that.
 236          */
 237         virtual Bool_t IsEqual(const TObject *obj) const;
 238
 239         /**
 240          * Comparison operator to check if two sets of scalars have the same values.
 241          * \note The description strings are not checked so they could be different
 242          *   and the order of the scalars does not matter either.
 243          */
 244         bool operator == (const AliHLTScalars& obj) const;
 245
 246         /**
 247          * Comparison operator to check if two sets of scalars are different.
 248          * \note The description strings are not checked, only the values are.
 249          *   In addition, the order of the scalars does not matter.
 250          */
 251         bool operator != (const AliHLTScalars& obj) const
 252         {
 253                 return not (this->operator == (obj));
 254         }
 255
 256 protected:
 257
 258         /**
 259          * Constructor that can be used by deriving classes to overload the class stored
 260          * in the fScalars TClonesArray.
 261          * \param cl  The class to use in the fScalars as passed to the TClonesArray constructor.
 262          * \param initSize  The initial approximate number of elements in fScalars. (Default = 128).
 263          * \note The class used in <i>cl</i> must derive from AliHLTScalars::AliScalar.
 264          */
 265         AliHLTScalars(const TClass* cl, Int_t initSize = 128);
 266
 267         /**
 268          * This method creates a new scalar object in the fScalars TClonesArray.
 269          * \param i  Location of the new object to construct in the TClonesArray.
 270          * \param name  The name of the new scalar.
 271          * \param description  The description of the new scalar.
 272          * \param value  The value of the new scalar.
 273          * \returns the pointer to the new object created.
 274          * \note This method must be overridden by classes inheriting from this class if
 275          *    the protected AliHLTScalars(const TClass*, Int_t) constructor is used to
 276          *    change the class stored in the fScalars TClonesArray.
 277          *    One should use the method ScalarForConstructor to get the location where
 278          *    the new scalar object will be constructed.
 279          */
 280         virtual AliScalar* NewScalar(UInt_t i, const char* name, const char* description, Double_t value);
 281
 282         /**
 283          * Returns a pointer to the memory where a new scalar object should be constructed.
 284          * \param i  The position of the new object.
 285          */
 286         TObject*& ScalarForConstructor(UInt_t i) { return fScalars[Int_t(i)]; }
 287
 288         /**
 289          * This method should return an empty sentinel object to mark that a scalar was
 290          * not found in the list.
 291          * \note This method must be overridden by classes inheriting from this class if
 292          *    the protected AliHLTScalars(const TClass*, Int_t) constructor is used to
 293          *    change the class stored in the fScalars TClonesArray.
 294          */
 295         virtual const AliScalar& Sentinel() const;
 296
 297         /**
 298          * This is an internal Add method which can be faster to use than the public Add method
 299          * directly for classes derived from AliHLTScalars.
 300          * \param [out] scalar This gets filled with the pointer of the new scalar created or
 301          *    the existing one found.
 302          * \param [in] name The name of the scalar.
 303          * \param [in] description  A short description of the scalar.
 304          * \param [in] value  The value of the new scalar.
 305          * \returns true if the scalar already exists and false otherwise.
 306          */
 307         bool Add(AliScalar*& scalar, const char* name, const char* description, Double_t value);
 308
 309         /**
 310          * Utility method for classes deriving from AliHLTScalars to fetch the i'th scalar
 311          * from the TClonesArray without checking that the index is valid.
 312          * \param i  The index number of the scalar to fetch.
 313          */
 314         AliScalar* ScalarUncheckedAt(UInt_t i) const { return static_cast<AliScalar*>(fScalars.UncheckedAt(Int_t(i))); }
 315
 316 private:
 317
 318         TClonesArray fScalars;  // List of scalar objects.
 319         THashTable fMap;        //! Hash table of pointers to the scalars for fast lookup.
 320
 321         ClassDef(AliHLTScalars, 1);  // Set of HLT scalars.
 322 };
 323
 324 #endif // AliHLTSCALARS_H