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 list <i>[out]</i>: 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 list <i>[out]</i>: 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 constBase        <i>[out]</i>: additive part, independent of the
 112    *                                   input data volume
 113    * @param inputMultiplier  <i>[out]</i>: multiplication ratio
 114    */
 115   virtual void GetOutputDataSize(unsigned long& constBase, double& inputMultiplier);
 116
 117  protected:
 118
 119   /// Not implemented.
 120   AliHLTTrigger(const AliHLTTrigger& obj);
 121   /// Not implemented.
 122   AliHLTTrigger& operator = (const AliHLTTrigger& obj);
 123
 124   /**
 125    * This method needs to be implemented by child classes to implement the actual
 126    * trigger algorithm. A positive trigger decision is made by calling the TriggerEvent
 127    * method with TriggerEvent(true), or TriggerEvent(false) for a negative result
 128    * (no trigger).
 129    * If the AliHLTComponentEventData structure is needed for the current event being
 130    * processed then the GetEventData method can be used to fetch it.
 131    * Similarly, the AliHLTComponentTriggerData structure can be fetched with a call
 132    * to GetTriggerData.
 133    * @return Zero should be returned on success and a negative error code, which is
 134    *     compatible with the AliHLTSystem framework, on failure.
 135    */
 136   virtual int DoTrigger() = 0;
 137
 138   /**
 139    * Fills the output with the trigger decision. This should be called in the DoTrigger
 140    * method when a trigger decision has been made.
 141    * @param value  The trigger decision value. True for positive trigger and false
 142    *     for a negative result. (true by default)
 143    * \returns zero on success and negative value on failure. The possible failure
 144    *    codes are:<br>
 145    *     -ENOSPC - If there is not enough output buffer space for the trigger decision.<br>
 146    *     -ENOMSG - If the trigger decision object could not be serialised.
 147    */
 148   int TriggerEvent(bool value = true);
 149
 150   /**
 151    * Fills the output with the given trigger decision. This should be called in the
 152    * DoTrigger method when a custom trigger decision has been constructed.
 153    * @param result    The custom trigger decision object.
 154    * @param type  The data block type to use (set to
 155    *    kAliHLTDataTypeTObject|kAliHLTDataOriginOut by default).
 156    * @param spec  The data block specification to use (set to kAliHLTVoidDataSpec
 157    *    by default).
 158    * \returns zero on success and negative value on failure. The possible failure
 159    *    codes are:<br>
 160    *     -ENOSPC - If there is not enough output buffer space for the trigger decision.<br>
 161    *     -ENOMSG - If the trigger decision object could not be serialised.<br>
 162    *     -EINVAL - If the <i>result</i> object is NULL.
 163    */
 164   int TriggerEvent(
 165       AliHLTTriggerDecision* result,
 166       const AliHLTComponentDataType& type = kAliHLTDataTypeTObject|kAliHLTDataOriginOut,
 167       AliHLTUInt32_t spec = kAliHLTVoidDataSpec
 168     );
 169
 170   /**
 171    * Method for finding out the result of the last call to TriggerEvent.
 172    * \returns the error code for the last call to TriggerEvent.
 173    */
 174   int GetLastTriggerEventResult() const { return fTriggerEventResult; }
 175
 176   /**
 177    * Returns the event data structure for the current event.
 178    * NULL is returned if this method is not called inside the DoTrigger method.
 179    */
 180   const AliHLTComponentEventData* GetEventData() const { return fEventData; }
 181
 182   /**
 183    * Returns the trigger data structure for the current event.
 184    * NULL is returned if this method is not called inside the DoTrigger method.
 185    */
 186   AliHLTComponentTriggerData* GetTriggerData() const { return fTriggerData; }
 187
 188   /**
 189    * Set a bit to 1 in the readout list which will enable that DDL for readout
 190    * @param ddlId     Equipment ID of DDL to readout, in decimal.
 191    */
 192   void EnableDDLBit(Int_t ddlId)
 193   {
 194     AliHLTComponent::SetDDLBit(fReadoutList, ddlId, kTRUE);
 195   }
 196
 197   /**
 198    * Set a bit to 0 in the readout list which will exclude that DDL from the readout.
 199    * @param ddlId     Equipment ID of DDL not to readout, in decimal.
 200    */
 201   void DisableDDLBit(Int_t ddlId)
 202   {
 203     AliHLTComponent::SetDDLBit(fReadoutList, ddlId, kFALSE);
 204   }
 205
 206   /**
 207    * Set or unset bit in the readout list.
 208    * @param ddlId     Equipment ID of DDL to set, in decimal.
 209    * @param state     kTRUE will enable readout of that DDL, kFALSE will disable readout.
 210    */
 211   void SetDDLBit(Int_t ddlId, Bool_t state)
 212   {
 213     AliHLTComponent::SetDDLBit(fReadoutList, ddlId, state);
 214   }
 215
 216   /**
 217    * Returns the DDL readout list.
 218    */
 219   const AliHLTReadoutList& GetReadoutList() const { return fReadoutList; }
 220
 221   /**
 222    * Returns the DDL readout list for modification by hand.
 223    */
 224   AliHLTReadoutList& GetReadoutList() { return fReadoutList; }
 225
 226   /**
 227    * Sets the readout list object.
 228    * \param value  The new value to use for the readout list.
 229    */
 230   void SetReadoutList(const AliHLTReadoutList& value) { fReadoutList = value; }
 231
 232   /**
 233    * Returns the trigger domain object.
 234    */
 235   const AliHLTTriggerDomain& GetTriggerDomain() const { return fTriggerDomain; }
 236
 237   /**
 238    * Returns the trigger domain object for modification.
 239    */
 240   AliHLTTriggerDomain& GetTriggerDomain() { return fTriggerDomain; }
 241
 242   /**
 243    * Sets the trigger domain object.
 244    * \param value  The new value to use for the trigger domain.
 245    */
 246   void SetTriggerDomain(const AliHLTTriggerDomain& value) { fTriggerDomain = value; }
 247
 248   /**
 249    * Returns the trigger description string.
 250    */
 251   const char* GetDescription() const { return fDescription.Data(); }
 252
 253   /**
 254    * Sets the trigger description string.
 255    * \param value  The new value to use for the description string.
 256    */
 257   void SetDescription(const char* value) { fDescription = value; }
 258
 259   /**
 260    * \returns true if the trigger description, trigger domain and readout list
 261    *    should be cleared for each new event.
 262    */
 263   bool WillClearInfoForNewEvent() const { return fClearInfo; }
 264
 265   /**
 266    * Sets the flag indicating in the trigger description, trigger domain and
 267    * readout list should be cleared for each new event.
 268    * \param value  The new value to use for the flag.
 269    */
 270   void ClearInfoForNewEvent(bool value = true) { fClearInfo = value; }
 271
 272   /**
 273    * Create the EventDoneData and add the specified readout list
 274    * from a Trigger domain object.
 275    * @param domain   the domain as calculated by the (Global)trigger
 276    * @param type     type of the readout list, defined by PubSub
 277    *                  4 monitoring filter
 278    */
 279   int CreateEventDoneReadoutFilter(const AliHLTTriggerDomain& domain, unsigned type);
 280
 281  private:
 282
 283   /**
 284    * Inherited from AliHLTComponent. This method will clear the fDecisionMade flag,
 285    * remember the evtData and trigData pointers, then call DoTrigger to invoke the
 286    * actual trigger algorithm.
 287    */
 288   virtual int DoEvent(const AliHLTComponentEventData& evtData, AliHLTComponentTriggerData& trigData);
 289
 290   using AliHLTProcessor::DoEvent;
 291
 292   /**
 293    * Inherited from AliHLTComponent. This method is deprecated so hide it.
 294    * @return kAliHLTMultipleDataType is returned.
 295    */
 296   virtual AliHLTComponentDataType GetOutputDataType() { return kAliHLTMultipleDataType; };
 297
 298   /**
 299    * Inherited from AliHLTComponent. This method is deprecated so we hide it.
 300    * Rather use the const version of this method which this method calls anyway.
 301    * @param list     list to receive the output data types.
 302    */
 303   virtual void GetInputDataTypes(AliHLTComponentDataTypeList& list);
 304
 305   /**
 306    * Inherited from AliHLTComponent. This method is replaced with one that is
 307    * symmetric to GetInputDataTypes that returns void, so we make this method
 308    * private. The list will always contain kAliHLTDataTypeTObject, including whatever
 309    * values were added by the const version of GetOutputDataTypes.
 310    * @param list     list to receive the output data types.
 311    * @return the number of elements in the list.
 312    */
 313   virtual int GetOutputDataTypes(AliHLTComponentDataTypeList& list);
 314
 315   const AliHLTComponentEventData* fEventData; //! Event data for the current event. Only valid inside DoTrigger.
 316   AliHLTComponentTriggerData* fTriggerData; //! Trigger data for the current event. Only valid inside DoTrigger.
 317   bool fDecisionMade;  //! Flag indicating if the trigger decision has been made for this trigger yet.
 318   bool fClearInfo;  //! Flag indicating if fDescription, fReadoutList and fTriggerDomain should be cleared for each new event.
 319   int fTriggerEventResult;  //! Result returned by PushBack method in the TriggerEvent method.
 320   TString fDescription;   //! The description to use for the trigger decision.
 321   AliHLTReadoutList fReadoutList; //! The DDL readout list object for the current event being processed.
 322   AliHLTTriggerDomain fTriggerDomain; //! The trigger domain object for the current event being processed.
 323
 324   ClassDef(AliHLTTrigger, 0) // Base class for HLT triggers.
 325
 326 };
 327
 328 #endif // ALIHLTTRIGGER_H
 329