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    * This method allows one to completely ignore an event. The DoEvent method will
 172    * not even generate a false trigger decision if this method is called.
 173    */
 174   void IgnoreEvent(bool value = true) { fDecisionMade = value; }
 175
 176   /**
 177    * Method for finding out the result of the last call to TriggerEvent.
 178    * \returns the error code for the last call to TriggerEvent.
 179    */
 180   int GetLastTriggerEventResult() const { return fTriggerEventResult; }
 181
 182   /**
 183    * Returns the event data structure for the current event.
 184    * NULL is returned if this method is not called inside the DoTrigger method.
 185    */
 186   const AliHLTComponentEventData* GetEventData() const { return fEventData; }
 187
 188   /**
 189    * Returns the trigger data structure for the current event.
 190    * NULL is returned if this method is not called inside the DoTrigger method.
 191    */
 192   AliHLTComponentTriggerData* GetTriggerData() const { return fTriggerData; }
 193
 194   /**
 195    * Set a bit to 1 in the readout list which will enable that DDL for readout
 196    * @param ddlId     Equipment ID of DDL to readout, in decimal.
 197    */
 198   void EnableDDLBit(Int_t ddlId)
 199   {
 200     AliHLTComponent::SetDDLBit(fReadoutList, ddlId, kTRUE);
 201   }
 202
 203   /**
 204    * Set a bit to 0 in the readout list which will exclude that DDL from the readout.
 205    * @param ddlId     Equipment ID of DDL not to readout, in decimal.
 206    */
 207   void DisableDDLBit(Int_t ddlId)
 208   {
 209     AliHLTComponent::SetDDLBit(fReadoutList, ddlId, kFALSE);
 210   }
 211
 212   /**
 213    * Set or unset bit in the readout list.
 214    * @param ddlId     Equipment ID of DDL to set, in decimal.
 215    * @param state     kTRUE will enable readout of that DDL, kFALSE will disable readout.
 216    */
 217   void SetDDLBit(Int_t ddlId, Bool_t state)
 218   {
 219     AliHLTComponent::SetDDLBit(fReadoutList, ddlId, state);
 220   }
 221
 222   /**
 223    * Returns the DDL readout list.
 224    */
 225   const AliHLTReadoutList& GetReadoutList() const { return fReadoutList; }
 226
 227   /**
 228    * Returns the DDL readout list for modification by hand.
 229    */
 230   AliHLTReadoutList& GetReadoutList() { return fReadoutList; }
 231
 232   /**
 233    * Sets the readout list object.
 234    * \param value  The new value to use for the readout list.
 235    */
 236   void SetReadoutList(const AliHLTReadoutList& value) { fReadoutList = value; }
 237
 238   /**
 239    * Returns the trigger domain object.
 240    */
 241   const AliHLTTriggerDomain& GetTriggerDomain() const { return fTriggerDomain; }
 242
 243   /**
 244    * Returns the trigger domain object for modification.
 245    */
 246   AliHLTTriggerDomain& GetTriggerDomain() { return fTriggerDomain; }
 247
 248   /**
 249    * Sets the trigger domain object.
 250    * \param value  The new value to use for the trigger domain.
 251    */
 252   void SetTriggerDomain(const AliHLTTriggerDomain& value) { fTriggerDomain = value; }
 253
 254   /**
 255    * Returns the trigger description string.
 256    */
 257   const char* GetDescription() const { return fDescription.Data(); }
 258
 259   /**
 260    * Sets the trigger description string.
 261    * \param value  The new value to use for the description string.
 262    */
 263   void SetDescription(const char* value) { fDescription = value; }
 264
 265   /**
 266    * \returns true if the trigger description, trigger domain and readout list
 267    *    should be cleared for each new event.
 268    */
 269   bool WillClearInfoForNewEvent() const { return fClearInfo; }
 270
 271   /**
 272    * Sets the flag indicating in the trigger description, trigger domain and
 273    * readout list should be cleared for each new event.
 274    * \param value  The new value to use for the flag.
 275    */
 276   void ClearInfoForNewEvent(bool value = true) { fClearInfo = value; }
 277
 278   /**
 279    * Create the EventDoneData and add the specified readout list
 280    * from a Trigger domain object.
 281    * @param domain   the domain as calculated by the (Global)trigger
 282    * @param type     type of the readout list, defined by PubSub
 283    *                  3 monitoring filter
 284    *                  4 monitoring filter
 285    *                  5 monitoring filter
 286    */
 287   int CreateEventDoneReadoutFilter(const AliHLTTriggerDomain& domain, unsigned type);
 288
 289  private:
 290
 291   /**
 292    * Inherited from AliHLTComponent. This method will clear the fDecisionMade flag,
 293    * remember the evtData and trigData pointers, then call DoTrigger to invoke the
 294    * actual trigger algorithm.
 295    */
 296   virtual int DoEvent(const AliHLTComponentEventData& evtData, AliHLTComponentTriggerData& trigData);
 297
 298   using AliHLTProcessor::DoEvent;
 299
 300   /**
 301    * Inherited from AliHLTComponent. This method is deprecated so hide it.
 302    * @return kAliHLTMultipleDataType is returned.
 303    */
 304   virtual AliHLTComponentDataType GetOutputDataType() { return kAliHLTMultipleDataType; };
 305
 306   /**
 307    * Inherited from AliHLTComponent. This method is deprecated so we hide it.
 308    * Rather use the const version of this method which this method calls anyway.
 309    * @param list     list to receive the output data types.
 310    */
 311   virtual void GetInputDataTypes(AliHLTComponentDataTypeList& list);
 312
 313   /**
 314    * Inherited from AliHLTComponent. This method is replaced with one that is
 315    * symmetric to GetInputDataTypes that returns void, so we make this method
 316    * private. The list will always contain kAliHLTDataTypeTObject, including whatever
 317    * values were added by the const version of GetOutputDataTypes.
 318    * @param list     list to receive the output data types.
 319    * @return the number of elements in the list.
 320    */
 321   virtual int GetOutputDataTypes(AliHLTComponentDataTypeList& list);
 322
 323   const AliHLTComponentEventData* fEventData; //! Event data for the current event. Only valid inside DoTrigger.
 324   AliHLTComponentTriggerData* fTriggerData; //! Trigger data for the current event. Only valid inside DoTrigger.
 325   bool fDecisionMade;  //! Flag indicating if the trigger decision has been made for this trigger yet.
 326   bool fClearInfo;  //! Flag indicating if fDescription, fReadoutList and fTriggerDomain should be cleared for each new event.
 327   int fTriggerEventResult;  //! Result returned by PushBack method in the TriggerEvent method.
 328   TString fDescription;   //! The description to use for the trigger decision.
 329   AliHLTReadoutList fReadoutList; //! The DDL readout list object for the current event being processed.
 330   AliHLTTriggerDomain fTriggerDomain; //! The trigger domain object for the current event being processed.
 331
 332   ClassDef(AliHLTTrigger, 0) // Base class for HLT triggers.
 333
 334 };
 335
 336 #endif // ALIHLTTRIGGER_H
 337