#include "TArrayL64.h"
#include "TObjArray.h"
+/**
+ * \class AliHLTGlobalTriggerDecision
+ * The global trigger decision object is generated by the AliHLTGlobalTriggerComponent
+ * class during processing of input triggers.
+ *
+ * Multiple input trigger components deriving from AliHLTTrigger will generate
+ * AliHLTTriggerDecision objects and possibly additional summary objects. All these
+ * objects are input for the global trigger component AliHLTGlobalTriggerComponent.
+ * After processing the input objects based on the trigger menu encoded in AliHLTTriggerMenu,
+ * the global trigger will generate and fill an AliHLTGlobalTriggerDecision object
+ * based on its decision. The new object will contain all the information a normal
+ * AliHLTTriggerDecision object generated by AliHLTTrigger contains. But in addition
+ * all the input objects that contributed to the global decision are also stored
+ * inside AliHLTGlobalTriggerDecision. The contributing trigger decisions are filled
+ * in fContributingTriggers and contributing summary TObjects are filled into fInputObjects.
+ * These can be accessed with the following methods:
+ * <i>NumberOfTriggerInputs</i> <i>TriggerInput</i> <i>TriggerInputs</i> for the
+ * trigger inputs;
+ * and <i>NumberOfInputObjects</i> <i>InputObject</i> <i>InputObjects</i> for the
+ * input summary objects.
+ *
+ * There is also an array of counters stored in the global decision. These are
+ * a copy of the internal counters of the global trigger component. There is one
+ * counter for every item in the trigger menu, plus a possible additional counter
+ * at the end which indicated the total number of events processed by the global
+ * trigger component.
+ *
+ * \note The counters do not necessarily correspond to the actual number of triggers
+ * that are recorded in the HLT output data stream. For most simple trigger menu
+ * configurations the counters will indeed correspond the the actual number of triggers
+ * recorded. But for more complex menus that use non zero prescalar values this may not
+ * be the case. The reason is that the counters array returned is the internal counter
+ * values (state) of the global trigger component. The counters are used to make the
+ * prescalars work. Thus, every time a corresponding trigger condition matches
+ * (evaluates to true) the counter is incremented, but the trigger decision might
+ * anyway skip the corresponding trigger in the menu since the prescalar is downscaling
+ * the trigger rate for that particular trigger menu item. This means that the counter
+ * values will be an upper bound.
+ * The real count and rate of particular triggers should always be taken by actually
+ * counting the trigger decision result.
+ */
class AliHLTGlobalTriggerDecision : public AliHLTTriggerDecision
{
public:
virtual ~AliHLTGlobalTriggerDecision();
/**
- * Copy constructor
+ * Copy constructor performs a deep copy.
*/
- AliHLTGlobalTriggerDecision(const AliHLTGlobalTriggerDecision& src);
+ AliHLTGlobalTriggerDecision(const AliHLTGlobalTriggerDecision& src);
/**
- * Assignment operator
+ * Assignment operator performs a deep copy.
*/
- AliHLTGlobalTriggerDecision& operator=(const AliHLTGlobalTriggerDecision& src);
+ AliHLTGlobalTriggerDecision& operator=(const AliHLTGlobalTriggerDecision& src);
/**
* Inherited from TObject, this prints the contents of the trigger decision.
const TObjArray& InputObjects() const { return fInputObjects; }
/**
- * Adds a input object to the list of input objects that were considered when
+ * Adds an input object to the list of input objects that were considered when
* making this global trigger decision.
* \param object The input object to add.
* \note A copy of the object is made with TObject::Clone() and added.
*/
- void AddInputObject(const TObject* object)
- {
- fInputObjects.Add(object->Clone());
- }
+ void AddInputObject(const TObject* object);
+
+ /**
+ * Adds an input object to the list of input objects that were considered when
+ * making this global trigger decision.
+ * \param object The input object to add.
+ * \param own If true then the global trigger decision takes ownership of the
+ * object and will delete it when destroyed. The caller must not delete the
+ * object after this method call. The default is false (ownership is not taken).
+ * \note Unlike AddInputObject, the object pointer is added directly without creating
+ * a deep copy of the object. This means that the added object can only be deleted
+ * after this global trigger object is no longer using the object, unless <i>own</i>
+ * is true. If <i>own</i> is true then the object must not be deleted by the caller.
+ * \note The kCanDelete bit of the object is modified by this method call and is
+ * used to track who the object belongs to. This bit should not be modified for
+ * the object after a call to this method, until the decision object is cleared
+ * or destroyed.
+ */
+ void AddInputObjectRef(TObject* object, bool own = false);
/**
* Sets the counter array.
- * If the number of events is specified, an additional counter is added at the end.
+ * If the number of events is specified, an additional counter is added at the end
+ * and filled with <i>eventCount</i> which indicates the number of events that have been counted.
+ * \param counters The array of new counter values that the internal counters should be set to.
+ * \param eventCount This should be the total number of events processed. If it is
+ * a positive number >= 0 then the extra counter is added to the array and filled
+ * with the value of <i>eventCount</i>.
*/
- void SetCounters(const TArrayL64& counters, Long64_t eventCount=0);
+ void SetCounters(const TArrayL64& counters, Long64_t eventCount = -1);
/**
* Returns the event trigger counters associated with the global trigger classes.
+ * There is one counter for every trigger menu item that the global trigger component
+ * was configured with. Thus the first counter will correspond to the first menu item
+ * added to the trigger menu, the second counter for the second item added and so on.
+ * If the total number of events processed counter is pressent it will be at the
+ * end of the array in position N-1 where N is the number of items in the counter
+ * array (also this will correspond to N-1 trigger menu items in the global trigger menu).
+ *
+ * \note The counters do not necessarily correspond to the actual number of trigger
+ * that are recorded in the HLT output data stream. For most simple trigger menu
+ * configurations the counters will indeed correspond the the actual number of triggers
+ * recorded. But for more complex menus which use prescalar values this may not be
+ * the case. The reason is that the counters array returned is the internal counter
+ * values (state) of the global trigger component. The counters are used to make the
+ * prescalars work. Thus every time a corresponding trigger condition matches
+ * (evaluates to true) the counter is incremented, but the trigger decision might
+ * anyhow skip the corresponding trigger in the menu since the prescalar is downscaling
+ * the trigger rate for that particular trigger menu item.
*/
const TArrayL64& Counters() const { return fCounters; }
+ /**
+ * This method removes clears the trigger domain, sets the decision result to false
+ * and clears the input object arrays and counters.
+ * \param option This is passed onto the internal array clear methods.
+ * The method is inherited from TObject.
+ */
+ virtual void Clear(Option_t* option = "C");
+
+ /**
+ * Finds a named input object from the list of contributing triggers and other input objects.
+ * i.e. Both the arrays returned by TriggerInputs() and InputObjects() will be searched,
+ * but the contributing triggers will be searched first.
+ * \param name The name of the object to match as returned by the objects GetName() method.
+ * \returns a pointer to the object found or NULL if none was found.
+ * The method is inherited from TObject.
+ */
+ virtual /*const*/ TObject* FindObject(const char* name) const;
+
+ /**
+ * Finds a matching object from the list of contributing triggers and other input objects
+ * by comparing the given object to objects in the lists with the IsEqual() method.
+ * i.e. Both the arrays returned by TriggerInputs() and InputObjects() will be searched,
+ * but the contributing triggers will be searched first.
+ * \param obj The object to match to with the IsEqual() method.
+ * \returns a pointer to the object found or NULL if none was found.
+ * The method is inherited from TObject.
+ */
+ virtual /*const*/ TObject* FindObject(const TObject* obj) const;
+
+ /**
+ * This method is called in the streamer to mark the entries in
+ * fInputObjects as owned and deletable. MUST be public for
+ * streamer evolution to work.
+ */
+ void MarkInputObjectsAsOwned();
private:
+ /**
+ * Deletes all the input objects in fInputObjects that are marked with kCanDelete
+ * and empties the whole array.
+ */
+ void DeleteInputObjects();
+
+
TClonesArray fContributingTriggers; /// The list of contributing trigger decisions from all AliHLTTrigger components that were considered.
TObjArray fInputObjects; /// The list of other input objects.
TArrayL64 fCounters; /// Event trigger counters. One counter for each trigger class in the global trigger.