HLT/trigger/AliHLTTrigger.h

   1 //-*- Mode: C++ -*-
   2 // $Id$
   3 #ifndef ALIHLTTRIGGER_H
   4 #define ALIHLTTRIGGER_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   AliHLTTrigger.cxx
  10 /// @author Artur Szostak <artursz@iafrica.com>
  11 /// @date   12 Aug 2008
  12 /// @brief  Declaration of the AliHLTTrigger base component class.
  13
  14 #include "AliHLTProcessor.h"
  15 #include "AliHLTReadoutList.h"
  16 #include "AliHLTTriggerDomain.h"
  17
  18 class AliHLTTriggerDecision;
  19
  20 /**
  21  * \class AliHLTTrigger
  22  * This is the base class from which all HLT trigger components should inherit.
  23  *
  24  * The class implements an AliHLTProcessor and implements specific functions
  25  * for the implementation of a trigger component.
  26  *
  27  * Mandatory functions to be implemented by the child class
  28  * - GetTriggerName()                                        <br>
  29  *   must return a unique char string, serves also as component id
  30  * - DoTrigger()
  31  *   this is the processing method. Can loop over all input blocks and
  32  *   calculate a trigger decision based on the input
  33  * - Spawn()
  34  *   refer to AliHLTComponent::Spawn() for more details
  35  *
  36  * The class provides default methods for the following methods of the
  37  * component interface. The methods can still be overloaded if needed:
  38  * - AliHLTComponent::GetNumberOfInputBlocks()
  39  * - AliHLTComponent::GetInputDataTypes()
  40  * - AliHLTComponent::GetOutputDataType()
  41  * - AliHLTComponent::GetOutputDataTypes()
  42  * - AliHLTComponent::GetOutputDataSize()
  43  *
  44  * Within the DoTrigger() function, the component has access to the input
  45  * data via:
  46  * - AliHLTComponent::GetFirstInputObject()
  47  * - AliHLTComponent::GetNextInputObject()
  48  * - AliHLTComponent::GetFirstInputBlock()
  49  * - AliHLTComponent::GetNextInputBlock()
  50  * - GetEventData()
  51  * - GetTriggerData()
  52  *
  53  * Further information about the event and the external trigger classes
  54  * can be checked by the base class methods:
  55  * - AliHLTComponent::EvaluateCTPTriggerClass()
  56  * - AliHLTComponent::GetRunNo() const;
  57  * - AliHLTComponent::GetRunType() const;
  58  * - AliHLTComponent::GetEventId()
  59  *
  60  * Inside DoTrigger() the component can call TriggerEvent() to create a
  61  * trigger. The trigger information is stored and propagated in an
  62  * AliHLTTriggerDecision object.
  63  *
  64  * \ingroup alihlt_trigger_components
  65  */
  66 class AliHLTTrigger : public AliHLTProcessor
  67 {
  68  public:
  69
  70   AliHLTTrigger();
  71   virtual ~AliHLTTrigger();
  72
  73   /**
  74    * Returns the name of the trigger. This must be unique across the system.
  75    * This method is pure virtual and must be implemented by child classes.
  76    * @return string containing the trigger name.
  77    * \note The name returned by this method should be a valid C++ symbol name.
  78    *    Otherwise the global trigger component will not be able to handle the
  79    *    derived trigger component properly.
  80    *    As an extention the '-' character is allowed in the symbol name,
  81    *    but not as the first character.
  82    */
  83   virtual const char* GetTriggerName() const = 0;
  84
  85   /**
  86    * Inherited from AliHLTComponent. Returns the name of the trigger by default.
  87    * @return string containing the trigger name as the component ID.
  88    */
  89   virtual const char* GetComponentID() { return GetTriggerName(); };
  90
  91   /**
  92    * Get the input data types of the component.
  93    * This method returns kAliHLTAnyDataType by default.
  94    * @param [out] list The list of data types to be filled.
  95    */
  96   virtual void GetInputDataTypes(AliHLTComponentDataTypeList& list) const;
  97
  98   /**
  99    * Returns extra output data types this trigger generates.
 100    * This returns kAliHLTDataTypeTriggerDecision by default.
 101    * @param [out] list The list of data types to be filled.
 102    * \note The underlying non const version of GetOutputDataTypes adds the value
 103    *    kAliHLTDataTypeReadoutList to the list automatically.
 104    */
 105   virtual void GetOutputDataTypes(AliHLTComponentDataTypeList& list) const;
 106
 107   /**
 108    * Get a ratio by how much the data volume is shrunk or enhanced.
 109    * The method returns a size proportional to the trigger name string length
 110    * for constBase, and 1 for inputMultiplier.
 111    * @param [out] constBase        Additive part, independent of the input data volume
 112    * @param [out] inputMultiplier  Multiplication ratio.
 113    */
 114   virtual void GetOutputDataSize(unsigned long& constBase, double& inputMultiplier);
 115
 116  protected:
 117
 118   /// Not implemented.
 119   AliHLTTrigger(const AliHLTTrigger& obj);
 120   /// Not implemented.
 121   AliHLTTrigger& operator = (const AliHLTTrigger& obj);
 122
 123   /**
 124    * This method needs to be implemented by child classes to implement the actual
 125    * trigger algorithm. A positive trigger decision is made by calling the TriggerEvent
 126    * method with TriggerEvent(true), or TriggerEvent(false) for a negative result
 127    * (no trigger).
 128    * If the AliHLTComponentEventData structure is needed for the current event being
 129    * processed then the GetEventData method can be used to fetch it.
 130    * Similarly, the AliHLTComponentTriggerData structure can be fetched with a call
 131    * to GetTriggerData.
 132    * @return Zero should be returned on success and a negative error code, which is
 133    *     compatible with the AliHLTSystem framework, on failure.
 134    */
 135   virtual int DoTrigger() = 0;
 136
 137   /**
 138    * Fills the output with the trigger decision. This should be called in the DoTrigger
 139    * method when a trigger decision has been made.
 140    * @param value  The trigger decision value. True for positive trigger and false
 141    *     for a negative result. (true by default)
 142    * \returns zero on success and negative value on failure. The possible failure
 143    *    codes are:<br>
 144    *     -ENOSPC - If there is not enough output buffer space for the trigger decision.<br>
 145    *     -ENOMSG - If the trigger decision object could not be serialised.
 146    */
 147   int TriggerEvent(bool value = true);
 148
 149   /**
 150    * Fills the output with the given trigger decision. This should be called in the
 151    * DoTrigger method when a custom trigger decision has been constructed.
 152    * @param result    The custom trigger decision object.
 153    * @param type  The data block type to use (set to
 154    *    kAliHLTDataTypeTObject|kAliHLTDataOriginOut by default).
 155    * @param spec  The data block specification to use (set to kAliHLTVoidDataSpec
 156    *    by default).
 157    * \returns zero on success and negative value on failure. The possible failure
 158    *    codes are:<br>
 159    *     -ENOSPC - If there is not enough output buffer space for the trigger decision.<br>
 160    *     -ENOMSG - If the trigger decision object could not be serialised.<br>
 161    *     -EINVAL - If the <i>result</i> object is NULL.
 162    */
 163   int TriggerEvent(
 164       AliHLTTriggerDecision* result,
 165       const AliHLTComponentDataType& type = kAliHLTDataTypeTObject|kAliHLTDataOriginOut,
 166       AliHLTUInt32_t spec = kAliHLTVoidDataSpec
 167     );
 168
 169   /**
 170    * This method allows one to completely ignore an event. The DoEvent method will
 171    * not even generate a false trigger decision if this method is called.
 172    */
 173   void IgnoreEvent(bool value = true) { fDecisionMade = value; }
 174
 175   /**
 176    * Method for finding out the result of the last call to TriggerEvent.
 177    * \returns the error code for the last call to TriggerEvent.
 178    */
 179   int GetLastTriggerEventResult() const { return fTriggerEventResult; }
 180
 181   /**
 182    * Returns the event data structure for the current event.
 183    * NULL is returned if this method is not called inside the DoTrigger method.
 184    */
 185   const AliHLTComponentEventData* GetEventData() const { return fEventData; }
 186
 187   /**
 188    * Returns the trigger data structure for the current event.
 189    * NULL is returned if this method is not called inside the DoTrigger method.
 190    */
 191   AliHLTComponentTriggerData* GetTriggerData() const { return fTriggerData; }
 192
 193   /**
 194    * Set a bit to 1 in the readout list which will enable that DDL for readout
 195    * @param ddlId     Equipment ID of DDL to readout, in decimal.
 196    */
 197   void EnableDDLBit(Int_t ddlId)
 198   {
 199     fReadoutList.EnableDDLBit(ddlId);
 200   }
 201
 202   /**
 203    * Set a bit to 0 in the readout list which will exclude that DDL from the readout.
 204    * @param ddlId     Equipment ID of DDL not to readout, in decimal.
 205    */
 206   void DisableDDLBit(Int_t ddlId)
 207   {
 208     fReadoutList.DisableDDLBit(ddlId);
 209   }
 210
 211   /**
 212    * Set or unset bit in the readout list.
 213    * @param ddlId     Equipment ID of DDL to set, in decimal.
 214    * @param state     kTRUE will enable readout of that DDL, kFALSE will disable readout.
 215    */
 216   void SetDDLBit(Int_t ddlId, Bool_t state)
 217   {
 218     fReadoutList.SetDDLBit(ddlId, state);
 219   }
 220
 221   /**
 222    * Returns the DDL readout list.
 223    */
 224   const AliHLTReadoutList& GetReadoutList() const { return fReadoutList; }
 225
 226   /**
 227    * Returns the DDL readout list for modification by hand.
 228    */
 229   AliHLTReadoutList& GetReadoutList() { return fReadoutList; }
 230
 231   /**
 232    * Sets the readout list object.
 233    * \param value  The new value to use for the readout list.
 234    */
 235   void SetReadoutList(const AliHLTReadoutList& value) { fReadoutList = value; }
 236
 237   /**
 238    * Returns the trigger domain object.
 239    */
 240   const AliHLTTriggerDomain& GetTriggerDomain() const { return fTriggerDomain; }
 241
 242   /**
 243    * Returns the trigger domain object for modification.
 244    */
 245   AliHLTTriggerDomain& GetTriggerDomain() { return fTriggerDomain; }
 246
 247   /**
 248    * Sets the trigger domain object.
 249    * \param value  The new value to use for the trigger domain.
 250    */
 251   void SetTriggerDomain(const AliHLTTriggerDomain& value) { fTriggerDomain = value; }
 252
 253   /**
 254    * Returns the trigger description string.
 255    */
 256   const char* GetDescription() const { return fDescription.Data(); }
 257
 258   /**
 259    * Sets the trigger description string.
 260    * \param value  The new value to use for the description string.
 261    */
 262   void SetDescription(const char* value) { fDescription = value; }
 263
 264   /**
 265    * \returns true if the trigger description, trigger domain and readout list
 266    *    should be cleared for each new event.
 267    */
 268   bool WillClearInfoForNewEvent() const { return fClearInfo; }
 269
 270   /**
 271    * Sets the flag indicating in the trigger description, trigger domain and
 272    * readout list should be cleared for each new event.
 273    * \param value  The new value to use for the flag.
 274    */
 275   void ClearInfoForNewEvent(bool value = true) { fClearInfo = value; }
 276
 277   /**
 278    * Create the EventDoneData and add the specified readout list
 279    * from a Trigger domain object.
 280    * @param domain   the domain as calculated by the (Global)trigger
 281    * @param type     type of the readout list, defined by PubSub
 282    *                  3 monitoring filter
 283    *                  4 monitoring filter
 284    *                  5 monitoring filter
 285    */
 286   int CreateEventDoneReadoutFilter(const AliHLTTriggerDomain& domain, unsigned type);
 287
 288  private:
 289
 290   /**
 291    * Inherited from AliHLTComponent. This method will clear the fDecisionMade flag,
 292    * remember the evtData and trigData pointers, then call DoTrigger to invoke the
 293    * actual trigger algorithm.
 294    */
 295   virtual int DoEvent(const AliHLTComponentEventData& evtData, AliHLTComponentTriggerData& trigData);
 296
 297   using AliHLTProcessor::DoEvent;
 298
 299   /**
 300    * Inherited from AliHLTComponent. This method is deprecated so hide it.
 301    * @return kAliHLTMultipleDataType is returned.
 302    */
 303   virtual AliHLTComponentDataType GetOutputDataType() { return kAliHLTMultipleDataType; };
 304
 305   /**
 306    * Inherited from AliHLTComponent. This method is deprecated so we hide it.
 307    * Rather use the const version of this method which this method calls anyway.
 308    * @param list     list to receive the output data types.
 309    */
 310   virtual void GetInputDataTypes(AliHLTComponentDataTypeList& list);
 311
 312   /**
 313    * Inherited from AliHLTComponent. This method is replaced with one that is
 314    * symmetric to GetInputDataTypes that returns void, so we make this method
 315    * private. The list will always contain kAliHLTDataTypeTObject, including whatever
 316    * values were added by the const version of GetOutputDataTypes.
 317    * @param list     list to receive the output data types.
 318    * @return the number of elements in the list.
 319    */
 320   virtual int GetOutputDataTypes(AliHLTComponentDataTypeList& list);
 321
 322   const AliHLTComponentEventData* fEventData; //! Event data for the current event. Only valid inside DoTrigger.
 323   AliHLTComponentTriggerData* fTriggerData; //! Trigger data for the current event. Only valid inside DoTrigger.
 324   bool fDecisionMade;  //! Flag indicating if the trigger decision has been made for this trigger yet.
 325   bool fClearInfo;  //! Flag indicating if fDescription, fReadoutList and fTriggerDomain should be cleared for each new event.
 326   int fTriggerEventResult;  //! Result returned by PushBack method in the TriggerEvent method.
 327   TString fDescription;   //! The description to use for the trigger decision.
 328   AliHLTReadoutList fReadoutList; //! The DDL readout list object for the current event being processed.
 329   AliHLTTriggerDomain fTriggerDomain; //! The trigger domain object for the current event being processed.
 330
 331   ClassDef(AliHLTTrigger, 0) // Base class for HLT triggers.
 332
 333 };
 334
 335 #endif // ALIHLTTRIGGER_H
 336