HLT/BASE/AliHLTTriggerMenu.h

   1 //-*- Mode: C++ -*-
   2 // $Id$
   3 #ifndef ALIHLTTRIGGERMENU_H
   4 #define ALIHLTTRIGGERMENU_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   AliHLTTriggerMenu.h
  10 /// @author Artur Szostak <artursz@iafrica.com>
  11 /// @date   19 Dec 2008
  12 /// @brief  Declaration of the AliHLTTriggerMenu base class.
  13
  14 #include "TObject.h"
  15 #include "TString.h"
  16 #include "TClonesArray.h"
  17 #include "AliHLTTriggerMenuSymbol.h"
  18 #include "AliHLTTriggerMenuItem.h"
  19 #include "AliHLTTriggerDomain.h"
  20
  21 /**
  22  * \class AliHLTTriggerMenu
  23  * The trigger menu specifies the HLT global trigger component configuration.
  24  * The global trigger has a list of individual input trigger components deriving
  25  * from AliHLTTrigger. Each one of these triggers is named. Thus, the trigger menu
  26  * is a list of trigger condition expressions, where the variables inside the
  27  * expressions are the names of the input triggers. In this way the global trigger
  28  * can be configured in a powerful manner using C++ expressions.
  29  * Attached to each trigger condition expression is a trigger domain merging
  30  * expression, which indicates how the final global trigger domain should be
  31  * calculated from the fragments coming from each individual trigger component.
  32  * Each entry in the trigger menu has a priority. These are set explicitly and
  33  * set to zero by default. The higher the priority number for a menu item the
  34  * higher its priority. Multiple items can have the same priority values.
  35  *
  36  * An important concept is the trigger priority group. This is a number of menu
  37  * items that all have the same priority. If all trigger menu items have the
  38  * same priority value then there is only one priority group with all the items
  39  * being members of the same group. Otherwise there can be any number of priority
  40  * groups with any number of one or more trigger menu items in a group.
  41  * A trigger menu item belongs to priority group N if it has a priority number equal
  42  * to N. The trigger menu is then evaluated by the global trigger component, such
  43  * that the highest priority trigger groups (largest N) are evaluated first.
  44  * Trigger items within a priority group are then evaluated in the order they
  45  * were added to the trigger menu. Thus, the first item added to the menu in group
  46  * N is evaluated first, and the last added to group N is evaluated last.
  47  * Inside a priority group all trigger menu items have their trigger condition
  48  * expressions evaluated. This is equivalent to evaluating the group's trigger
  49  * condition expression, where the group's expression is a concatenation of the
  50  * individual trigger condition expressions of the items in priority group N.
  51  * This means that the trigger conditions expressions (indeed, also the trigger
  52  * domain merging expressions) are allowed to have a dangling trailing operator.
  53  * The trailing operator will then make sense in the full concatenated expression.
  54  * If no such trailing operator is found then the default trigger conditions operator
  55  * is used implicitly for the concatenation, as defined in the trigger menu.
  56  * If the full concatenated condition expression evaluates to true then the priority
  57  * group's result is also true and the output trigger domain can be calculated.
  58  * This is done by taking all the merging expressions from only those trigger menu
  59  * items whose trigger condition expression fragments were true, and concatenating
  60  * those merging expression fragments together to arrive at the full merging expression.
  61  * The final trigger domain is calculated by evaluating the merging expression.
  62  * Note that the concatenation of the merging expression fragments works in the
  63  * same manner as the trigger condition expressions. So a trailing operator is
  64  * allowed in each trigger menu item's merging expression, and is implicitly removed
  65  * if not needed, but used to concatenate with the next triggered expression.
  66  * The default domain merging operator is used if no trailing operator is present
  67  * but a concatenation is required.
  68  * The evaluation of trigger menu items stops at the first priority group whose
  69  * trigger condition expression evaluated to true. This is important to force
  70  * mutually exclusive precedence of a higher priority trigger or triggers.
  71  * The two extremes of this model are:
  72  * - All trigger menu entries have the same priority so they are all part of the
  73  *   same priority group, and thus every trigger menu item is evaluated.
  74  * - Every trigger menu entry has a different priority, so each forms its own priority
  75  *   group, and the trigger evaluation stops at the first highest priority item
  76  *   that matches the trigger condition.
  77  * Another way to look at the model is that priority groups are mutually exclusive.
  78  * Trigger menu items from two different priority groups cannot be active at the same
  79  * time. While more than one trigger menu item can be active at the same time if they
  80  * are from the same priority group.
  81  * Yet another view at the model is that a priority group forms an explicit trigger
  82  * condition and trigger domain merging expression, while trigger menu items specify
  83  * the expression fragments that are concatenated together implicitly. If there is
  84  * just one trigger menu item in a priority group then the groups expressions are
  85  * explicit. On the other hand, for multiple items in a group they form implicit
  86  * expression fragments.
  87  *
  88  * \note CTP trigger class names can be used in the trigger menu since the global
  89  *   trigger will generate and add corresponding trigger decision objects to the
  90  *   logic on the fly.
  91  *   In addition, for software triggers, a special SOFTWARE trigger decision is
  92  *   generated and the SOFTWARE name can be used in the trigger menu for this.
  93  *   If the software trigger is a calibration event then a trigger decision with
  94  *   the name CALIBRATION is generated instead. START_OF_DATA and END_OF_DATA
  95  *   symbols are similarly defined for the start and end of data events respectively.
  96  */
  97 class AliHLTTriggerMenu : public TObject
  98 {
  99  public:
 100
 101   /**
 102    * Default constructor.
 103    */
 104   AliHLTTriggerMenu();
 105
 106   /**
 107    * Default destructor.
 108    */
 109   virtual ~AliHLTTriggerMenu();
 110
 111   /**
 112    * Inherited from TObject, this prints the contents of the trigger menu.
 113    * \param option  Can be "short" which will print the short format.
 114    */
 115   virtual void Print(Option_t* option = "") const;
 116
 117   /**
 118    * This method removes all items and symbols from the trigger menu.
 119    * \note The name and default values are not changed. Only the items and symbol
 120    *    lists are cleared.
 121    * \param  option  This is passed onto the internal fSymbols and fItems TClonesArrays.
 122    * The method is inherited from TObject.
 123    */
 124   virtual void Clear(Option_t* option = "");
 125
 126   /**
 127    * Copy constructor performs a deep copy of the object.
 128    * \param  obj  Object to copy from.
 129    */
 130   AliHLTTriggerMenu(const AliHLTTriggerMenu& obj);
 131
 132   /**
 133    * Assignment operator performs a deep copy of the object.
 134    * \param  obj  Object to copy from.
 135    * \return  This object is returned after being replaced by a copy of <i>obj</i>.
 136    */
 137   AliHLTTriggerMenu& operator = (const AliHLTTriggerMenu& obj);
 138
 139   /**
 140    * Inherited from TObject. Returns the name of the trigger menu.
 141    */
 142   virtual const char* GetName() const { return fName.Data(); }
 143
 144   /**
 145    * Returns the name of the trigger menu.
 146    */
 147   const char* Name() const { return fName.Data(); }
 148
 149   /**
 150    * Sets the name of the trigger menu.
 151    */
 152   void Name(const char* name) { fName = name; }
 153
 154   /**
 155    * Returns the number of symbols in the trigger menu.
 156    */
 157   UInt_t NumberOfSymbols() const { return UInt_t(fSymbols.GetEntriesFast()); }
 158
 159   /**
 160    * Fetches the i'th trigger menu symbol.
 161    */
 162   const AliHLTTriggerMenuSymbol* Symbol(UInt_t i) const
 163   {
 164     if (i >= UInt_t(fSymbols.GetEntriesFast())) return NULL;
 165     return static_cast<const AliHLTTriggerMenuSymbol*>( fSymbols.UncheckedAt(Int_t(i)) );
 166   }
 167
 168   /**
 169    * Fetches the i'th trigger menu symbol for editing.
 170    */
 171   AliHLTTriggerMenuSymbol* Symbol(UInt_t i)
 172   {
 173     if (i >= UInt_t(fSymbols.GetEntriesFast())) return NULL;
 174     return static_cast<AliHLTTriggerMenuSymbol*>( fSymbols.UncheckedAt(Int_t(i)) );
 175   }
 176
 177   /**
 178    * Adds a new symbol to the trigger menu. If the symbol being added already
 179    * exists in the trigger menu then the new symbol will not be added.
 180    * \param entry  The new trigger menu symbol being added.
 181    */
 182   void AddSymbol(const AliHLTTriggerMenuSymbol& entry);
 183
 184   /**
 185    * Returns the array of symbols.
 186    */
 187   const TClonesArray& SymbolArray() const { return fSymbols; }
 188
 189   /**
 190    * Returns the number of items in the trigger menu.
 191    */
 192   UInt_t NumberOfItems() const { return UInt_t(fItems.GetEntriesFast()); }
 193
 194   /**
 195    * Fetches the i'th trigger menu item.
 196    */
 197   const AliHLTTriggerMenuItem* Item(UInt_t i) const
 198   {
 199     if (i >= UInt_t(fItems.GetEntriesFast())) return NULL;
 200     return static_cast<const AliHLTTriggerMenuItem*>( fItems.UncheckedAt(Int_t(i)) );
 201   }
 202
 203   /**
 204    * Fetches the i'th trigger menu item for editing.
 205    */
 206   AliHLTTriggerMenuItem* Item(UInt_t i)
 207   {
 208     if (i >= UInt_t(fItems.GetEntriesFast())) return NULL;
 209     return static_cast<AliHLTTriggerMenuItem*>( fItems.UncheckedAt(Int_t(i)) );
 210   }
 211
 212   /**
 213    * Adds a new entry to the trigger menu.
 214    */
 215   void AddItem(const AliHLTTriggerMenuItem& entry)
 216   {
 217     new (fItems[fItems.GetEntriesFast()]) AliHLTTriggerMenuItem(entry);
 218   }
 219
 220   /**
 221    * Returns the array of menu items.
 222    */
 223   const TClonesArray& ItemsArray() const { return fItems; }
 224
 225   /**
 226    * Sets the default trigger description to use if the global trigger does not
 227    * fire and returns a negative result.
 228    */
 229   void DefaultDescription(const char* value) { fDefaultDescription = value; }
 230
 231   /**
 232    * Returns the default trigger description to use if the global trigger does not
 233    * fire and returns a negative result.
 234    */
 235   const char* DefaultDescription() const { return fDefaultDescription.Data(); }
 236
 237   /**
 238    * Sets the default trigger domain to use if the global trigger does not
 239    * fire and returns a negative result.
 240    */
 241   void DefaultTriggerDomain(const AliHLTTriggerDomain& value) { fDefaultDomain = value; }
 242
 243   /**
 244    * Returns the default trigger domain to use if the global trigger does not
 245    * fire and returns a negative result.
 246    */
 247   const AliHLTTriggerDomain& DefaultTriggerDomain() const { return fDefaultDomain; }
 248
 249   /**
 250    * Returns the default trigger domain for modification.
 251    */
 252   AliHLTTriggerDomain& DefaultTriggerDomain() { return fDefaultDomain; }
 253
 254   /**
 255    * Sets the default operator used to merge trigger conditions that are matched from
 256    * the same trigger menu priority group.
 257    */
 258   void DefaultConditionOperator(const char* value) { fDefaultConditionOperator = value; }
 259
 260   /**
 261    * Returns the default operator used to merge trigger conditions that are matched from
 262    * the same trigger menu priority group.
 263    */
 264   const char* DefaultConditionOperator() const { return fDefaultConditionOperator.Data(); }
 265
 266   /**
 267    * Sets the default operator used to merge trigger domains that are matched from
 268    * the same trigger menu priority group.
 269    */
 270   void DefaultDomainOperator(const char* value) { fDefaultDomainOperator = value; }
 271
 272   /**
 273    * Returns the default operator used to merge trigger domains that are matched from
 274    * the same trigger menu priority group.
 275    */
 276   const char* DefaultDomainOperator() const { return fDefaultDomainOperator.Data(); }
 277
 278   /**
 279    * Returns the default result for the global trigger if no item is matched.
 280    */
 281   bool DefaultResult() const { return TestBit(BIT(15)) == 1; }
 282
 283   /**
 284    * Set the default result for the global trigger if no item is matched.
 285    */
 286   void DefaultResult(bool value) { SetBit(BIT(15), value); }
 287
 288  private:
 289
 290   TString fName;  /// Name of the trigger menu.
 291   TClonesArray fSymbols;  /// List of symbols used in trigger expressions.
 292   TClonesArray fItems;  /// List of trigger menu items.
 293   TString fDefaultDescription; /// The default trigger description to use for negative global triggers.
 294   AliHLTTriggerDomain fDefaultDomain;  /// The default trigger domain to use for negative global triggers.
 295   TString fDefaultConditionOperator;  /// The default operator to use to merge trigger conditions from the same priority group.
 296   TString fDefaultDomainOperator;  /// The default operator to use to merge trigger domains from the same priority group.
 297
 298   ClassDef(AliHLTTriggerMenu, 4) // Trigger menu for the global HLT trigger.
 299 };
 300
 301 #endif // ALIHLTTRIGGERMENU_H
 302