HLT/BASE/AliHLTGlobalTriggerDecision.h

   1 //-*- Mode: C++ -*-
   2 // $Id$
   3 #ifndef ALIHLTGLOBALTRIGGERDECISION_H
   4 #define ALIHLTGLOBALTRIGGERDECISION_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   AliHLTGlobalTriggerDecision.h
  10 /// @author Artur Szostak <artursz@iafrica.com>
  11 /// @date   26 Nov 2008
  12 /// @brief  Declaration of the AliHLTGlobalTriggerDecision class storing the global HLT decision.
  13
  14 #include "AliHLTTriggerDecision.h"
  15 #include "TArrayL64.h"
  16 #include "TObjArray.h"
  17
  18 /**
  19  * \class AliHLTGlobalTriggerDecision
  20  * The global trigger decision object is generated by the AliHLTGlobalTriggerComponent
  21  * class during processing of input triggers.
  22  *
  23  * Multiple input trigger components deriving from AliHLTTrigger will generate
  24  * AliHLTTriggerDecision objects and possibly additional summary objects. All these
  25  * objects are input for the global trigger component AliHLTGlobalTriggerComponent.
  26  * After processing the input objects based on the trigger menu encoded in AliHLTTriggerMenu,
  27  * the global trigger will generate and fill an AliHLTGlobalTriggerDecision object
  28  * based on its decision. The new object will contain all the information a normal
  29  * AliHLTTriggerDecision object generated by AliHLTTrigger contains. But in addition
  30  * all the input objects that contributed to the global decision are also stored
  31  * inside AliHLTGlobalTriggerDecision. The contributing trigger decisions are filled
  32  * in fContributingTriggers and contributing summary TObjects are filled into fInputObjects.
  33  * These can be accessed with the following methods:
  34  *  <i>NumberOfTriggerInputs</i> <i>TriggerInput</i> <i>TriggerInputs</i> for the
  35  *  trigger inputs;
  36  *  and <i>NumberOfInputObjects</i> <i>InputObject</i> <i>InputObjects</i> for the
  37  *  input summary objects.
  38  *
  39  * There is also an array of counters stored in the global decision. These are
  40  * a copy of the internal counters of the global trigger component. There is one
  41  * counter for every item in the trigger menu, plus a possible additional counter
  42  * at the end which indicated the total number of events processed by the global
  43  * trigger component.
  44  *
  45  * \note The counters do not necessarily correspond to the actual number of triggers
  46  * that are recorded in the HLT output data stream. For most simple trigger menu
  47  * configurations the counters will indeed correspond the the actual number of triggers
  48  * recorded. But for more complex menus that use non zero prescalar values this may not
  49  * be the case. The reason is that the counters array returned is the internal counter
  50  * values (state) of the global trigger component. The counters are used to make the
  51  * prescalars work. Thus, every time a corresponding trigger condition matches
  52  * (evaluates to true) the counter is incremented, but the trigger decision might
  53  * anyway skip the corresponding trigger in the menu since the prescalar is downscaling
  54  * the trigger rate for that particular trigger menu item. This means that the counter
  55  * values will be an upper bound.
  56  * The real count and rate of particular triggers should always be taken by actually
  57  * counting the trigger decision result.
  58  */
  59 class AliHLTGlobalTriggerDecision : public AliHLTTriggerDecision
  60 {
  61  public:
  62
  63   /**
  64    * Default constructor.
  65    */
  66   AliHLTGlobalTriggerDecision();
  67
  68   /**
  69    * Constructor specifying multiple information fields.
  70    * \param result  The result of the global trigger decision.
  71    * \param triggerDomain  The trigger domain for the global trigger decision.
  72    * \param description  The description of (reason for) the global trigger decision.
  73    */
  74   AliHLTGlobalTriggerDecision(
  75       bool result, const AliHLTTriggerDomain& triggerDomain,
  76       const char* description = ""
  77     );
  78
  79   /**
  80    * Default destructor.
  81    */
  82   virtual ~AliHLTGlobalTriggerDecision();
  83
  84   /**
  85    * Copy constructor performs a deep copy.
  86    */
  87   AliHLTGlobalTriggerDecision(const AliHLTGlobalTriggerDecision& src);
  88
  89   /**
  90    * Assignment operator performs a deep copy.
  91    */
  92   AliHLTGlobalTriggerDecision& operator=(const AliHLTGlobalTriggerDecision& src);
  93
  94   /**
  95    * Inherited from TObject, this prints the contents of the trigger decision.
  96    * \param option  Can be "short" which will print the short format or "counters"
  97    *    which will print only the counters or "compact" which will print only the
  98    *    global information but not the lists of input objects.
  99    */
 100   virtual void Print(Option_t* option = "") const;
 101
 102   /**
 103    * Inherited from TObject. Copy this to the specified object.
 104    */
 105   virtual void Copy(TObject &object) const;
 106
 107   /**
 108    * Inherited from TObject. Create a new clone.
 109    */
 110   virtual TObject *Clone(const char *newname="") const;
 111
 112   /**
 113    * Returns the number of trigger inputs that contributed to this global trigger decision.
 114    */
 115   Int_t NumberOfTriggerInputs() const { return fContributingTriggers.GetEntriesFast(); }
 116
 117   /**
 118    * Returns the i'th trigger input object in fContributingTriggers.
 119    */
 120   const AliHLTTriggerDecision* TriggerInput(Int_t i) const
 121   {
 122     return static_cast<const AliHLTTriggerDecision*>( fContributingTriggers[i] );
 123   }
 124
 125   /**
 126    * Returns the list of trigger inputs used when making the global HLT trigger decision.
 127    */
 128   const TClonesArray& TriggerInputs() const { return fContributingTriggers; }
 129
 130   /**
 131    * Adds a trigger input to the list of triggers that were considered when making
 132    * this global trigger decision.
 133    * \param decision  The trigger decision object to add.
 134    */
 135   void AddTriggerInput(const AliHLTTriggerDecision& decision)
 136   {
 137     new (fContributingTriggers[fContributingTriggers.GetEntriesFast()]) AliHLTTriggerDecision(decision);
 138   }
 139
 140   /**
 141    * Returns the number of other input objects that contributed to this global trigger decision.
 142    */
 143   Int_t NumberOfInputObjects() const { return fInputObjects.GetEntriesFast(); }
 144
 145   /**
 146    * Returns the i'th input object in fInputObjects.
 147    */
 148   const TObject* InputObject(Int_t i) const { return fInputObjects[i]; }
 149
 150   /**
 151    * Returns the list of other input objects used when making the global HLT trigger decision.
 152    */
 153   const TObjArray& InputObjects() const { return fInputObjects; }
 154
 155   /**
 156    * Adds an input object to the list of input objects that were considered when
 157    * making this global trigger decision.
 158    * \param object  The input object to add.
 159    * \note  A copy of the object is made with TObject::Clone() and added.
 160    */
 161   void AddInputObject(const TObject* object);
 162
 163   /**
 164    * Adds an input object to the list of input objects that were considered when
 165    * making this global trigger decision.
 166    * \param object  The input object to add.
 167    * \param own  If true then the global trigger decision takes ownership of the
 168    *   object and will delete it when destroyed. The caller must not delete the
 169    *   object after this method call. The default is false (ownership is not taken).
 170    * \note Unlike AddInputObject, the object pointer is added directly without creating
 171    *   a deep copy of the object. This means that the added object can only be deleted
 172    *   after this global trigger object is no longer using the object, unless <i>own</i>
 173    *   is true. If <i>own</i> is true then the object must not be deleted by the caller.
 174    * \note The kCanDelete bit of the object is modified by this method call and is
 175    *   used to track who the object belongs to. This bit should not be modified for
 176    *   the object after a call to this method, until the decision object is cleared
 177    *   or destroyed.
 178    */
 179   void AddInputObjectRef(TObject* object, bool own = false);
 180
 181   /**
 182    * Sets the counter array.
 183    * If the number of events is specified, an additional counter is added at the end
 184    * and filled with <i>eventCount</i> which indicates the number of events that have been counted.
 185    * \param  counters  The array of new counter values that the internal counters should be set to.
 186    * \param  eventCount  This should be the total number of events processed. If it is
 187    *     a positive number >= 0 then the extra counter is added to the array and filled
 188    *     with the value of <i>eventCount</i>.
 189    */
 190   void SetCounters(const TArrayL64& counters, Long64_t eventCount = -1);
 191
 192   /**
 193    * Returns the event trigger counters associated with the global trigger classes.
 194    * There is one counter for every trigger menu item that the global trigger component
 195    * was configured with. Thus the first counter will correspond to the first menu item
 196    * added to the trigger menu, the second counter for the second item added and so on.
 197    * If the total number of events processed counter is pressent it will be at the
 198    * end of the array in position N-1 where N is the number of items in the counter
 199    * array (also this will correspond to N-1 trigger menu items in the global trigger menu).
 200    *
 201    * \note The counters do not necessarily correspond to the actual number of trigger
 202    * that are recorded in the HLT output data stream. For most simple trigger menu
 203    * configurations the counters will indeed correspond the the actual number of triggers
 204    * recorded. But for more complex menus which use prescalar values this may not be
 205    * the case. The reason is that the counters array returned is the internal counter
 206    * values (state) of the global trigger component. The counters are used to make the
 207    * prescalars work. Thus every time a corresponding trigger condition matches
 208    * (evaluates to true) the counter is incremented, but the trigger decision might
 209    * anyhow skip the corresponding trigger in the menu since the prescalar is downscaling
 210    * the trigger rate for that particular trigger menu item.
 211    */
 212   const TArrayL64& Counters() const { return fCounters; }
 213
 214   /**
 215    * This method removes clears the trigger domain, sets the decision result to false
 216    * and clears the input object arrays and counters.
 217    * \param  option  This is passed onto the internal array clear methods.
 218    * The method is inherited from TObject.
 219    */
 220   virtual void Clear(Option_t* option = "C");
 221
 222   /**
 223    * Finds a named input object from the list of contributing triggers and other input objects.
 224    * i.e. Both the arrays returned by TriggerInputs() and InputObjects() will be searched,
 225    * but the contributing triggers will be searched first.
 226    * \param  name  The name of the object to match as returned by the objects GetName() method.
 227    * \returns a pointer to the object found or NULL if none was found.
 228    * The method is inherited from TObject.
 229    */
 230   virtual /*const*/ TObject* FindObject(const char* name) const;
 231
 232   /**
 233    * Finds a matching object from the list of contributing triggers and other input objects
 234    * by comparing the given object to objects in the lists with the IsEqual() method.
 235    * i.e. Both the arrays returned by TriggerInputs() and InputObjects() will be searched,
 236    * but the contributing triggers will be searched first.
 237    * \param  obj  The object to match to with the IsEqual() method.
 238    * \returns a pointer to the object found or NULL if none was found.
 239    * The method is inherited from TObject.
 240    */
 241   virtual /*const*/ TObject* FindObject(const TObject* obj) const;
 242
 243   /**
 244    * This method is called in the streamer to mark the entries in
 245    * fInputObjects as owned and deletable.  MUST be public for
 246    * streamer evolution to work.
 247    */
 248   void MarkInputObjectsAsOwned();
 249  private:
 250
 251   /**
 252    * Deletes all the input objects in fInputObjects that are marked with kCanDelete
 253    * and empties the whole array.
 254    */
 255   void DeleteInputObjects();
 256
 257
 258   TClonesArray fContributingTriggers;  /// The list of contributing trigger decisions from all AliHLTTrigger components that were considered.
 259   TObjArray fInputObjects;  /// The list of other input objects.
 260   TArrayL64 fCounters;  /// Event trigger counters. One counter for each trigger class in the global trigger.
 261
 262   ClassDef(AliHLTGlobalTriggerDecision, 1) // Contains the HLT global trigger decision and information contributing to the decision.
 263 };
 264
 265 #endif // ALIHLTGLOBALTRIGGERDECISION_H
 266