Fixing problems with AliHLTGlobalTriggerComponent and failing test: testGlobalTrigger...
[u/mrichter/AliRoot.git] / 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    *                  4 monitoring filter
284    */
285   int CreateEventDoneReadoutFilter(const AliHLTTriggerDomain& domain, unsigned type);
286
287  private:
288  
289   /**
290    * Inherited from AliHLTComponent. This method will clear the fDecisionMade flag,
291    * remember the evtData and trigData pointers, then call DoTrigger to invoke the
292    * actual trigger algorithm.
293    */
294   virtual int DoEvent(const AliHLTComponentEventData& evtData, AliHLTComponentTriggerData& trigData);
295   
296   using AliHLTProcessor::DoEvent;
297  
298   /**
299    * Inherited from AliHLTComponent. This method is deprecated so hide it.
300    * @return kAliHLTMultipleDataType is returned.
301    */
302   virtual AliHLTComponentDataType GetOutputDataType() { return kAliHLTMultipleDataType; };
303  
304   /**
305    * Inherited from AliHLTComponent. This method is deprecated so we hide it.
306    * Rather use the const version of this method which this method calls anyway.
307    * @param list     list to receive the output data types.
308    */
309   virtual void GetInputDataTypes(AliHLTComponentDataTypeList& list);
310   
311   /**
312    * Inherited from AliHLTComponent. This method is replaced with one that is
313    * symmetric to GetInputDataTypes that returns void, so we make this method
314    * private. The list will always contain kAliHLTDataTypeTObject, including whatever
315    * values were added by the const version of GetOutputDataTypes.
316    * @param list     list to receive the output data types.
317    * @return the number of elements in the list.
318    */
319   virtual int GetOutputDataTypes(AliHLTComponentDataTypeList& list);
320   
321   const AliHLTComponentEventData* fEventData; //! Event data for the current event. Only valid inside DoTrigger.
322   AliHLTComponentTriggerData* fTriggerData; //! Trigger data for the current event. Only valid inside DoTrigger.
323   bool fDecisionMade;  //! Flag indicating if the trigger decision has been made for this trigger yet.
324   bool fClearInfo;  //! Flag indicating if fDescription, fReadoutList and fTriggerDomain should be cleared for each new event.
325   int fTriggerEventResult;  //! Result returned by PushBack method in the TriggerEvent method.
326   TString fDescription;   //! The description to use for the trigger decision.
327   AliHLTReadoutList fReadoutList; //! The DDL readout list object for the current event being processed.
328   AliHLTTriggerDomain fTriggerDomain; //! The trigger domain object for the current event being processed.
329   
330   ClassDef(AliHLTTrigger, 0) // Base class for HLT triggers.
331
332 };
333
334 #endif // ALIHLTTRIGGER_H
335