Updated macros for PHOS alignment calculation
[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 [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 DDL readout list block specification bits to be used.
239    */
240   AliHLTUInt32_t GetReadoutListSpecBits() const { return fReadoutListSpecBits; }
241
242   /**
243    * Sets the DDL readout list block specification bits to be used.
244    */
245   void SetReadoutListSpecBits(AliHLTUInt32_t spec) { fReadoutListSpecBits = spec; }
246   
247   /**
248    * Returns the trigger domain object.
249    */
250   const AliHLTTriggerDomain& GetTriggerDomain() const { return fTriggerDomain; }
251
252   /**
253    * Returns the trigger domain object for modification.
254    */
255   AliHLTTriggerDomain& GetTriggerDomain() { return fTriggerDomain; }
256
257   /**
258    * Sets the trigger domain object.
259    * \param value  The new value to use for the trigger domain.
260    */
261   void SetTriggerDomain(const AliHLTTriggerDomain& value) { fTriggerDomain = value; }
262   
263   /**
264    * Returns the trigger description string.
265    */
266   const char* GetDescription() const { return fDescription.Data(); }
267   
268   /**
269    * Sets the trigger description string.
270    * \param value  The new value to use for the description string.
271    */
272   void SetDescription(const char* value) { fDescription = value; }
273   
274   /**
275    * \returns true if the trigger description, trigger domain and readout list
276    *    should be cleared for each new event.
277    */
278   bool WillClearInfoForNewEvent() const { return fClearInfo; }
279   
280   /**
281    * Sets the flag indicating in the trigger description, trigger domain and
282    * readout list should be cleared for each new event.
283    * \param value  The new value to use for the flag.
284    */
285   void ClearInfoForNewEvent(bool value = true) { fClearInfo = value; }
286
287   /**
288    * Create the EventDoneData and add the specified readout list
289    * from a Trigger domain object.
290    * @param domain   the domain as calculated by the (Global)trigger
291    * @param type     type of the readout list, defined by PubSub
292    *                  3 monitoring filter
293    *                  4 monitoring filter
294    *                  5 monitoring filter
295    */
296   int CreateEventDoneReadoutFilter(const AliHLTTriggerDomain& domain, unsigned type);
297
298  private:
299  
300   /**
301    * Inherited from AliHLTComponent. This method will clear the fDecisionMade flag,
302    * remember the evtData and trigData pointers, then call DoTrigger to invoke the
303    * actual trigger algorithm.
304    */
305   virtual int DoEvent(const AliHLTComponentEventData& evtData, AliHLTComponentTriggerData& trigData);
306   
307   using AliHLTProcessor::DoEvent;
308  
309   /**
310    * Inherited from AliHLTComponent. This method is deprecated so hide it.
311    * @return kAliHLTMultipleDataType is returned.
312    */
313   virtual AliHLTComponentDataType GetOutputDataType() { return kAliHLTMultipleDataType; };
314  
315   /**
316    * Inherited from AliHLTComponent. This method is deprecated so we hide it.
317    * Rather use the const version of this method which this method calls anyway.
318    * @param list     list to receive the output data types.
319    */
320   virtual void GetInputDataTypes(AliHLTComponentDataTypeList& list);
321   
322   /**
323    * Inherited from AliHLTComponent. This method is replaced with one that is
324    * symmetric to GetInputDataTypes that returns void, so we make this method
325    * private. The list will always contain kAliHLTDataTypeTObject, including whatever
326    * values were added by the const version of GetOutputDataTypes.
327    * @param list     list to receive the output data types.
328    * @return the number of elements in the list.
329    */
330   virtual int GetOutputDataTypes(AliHLTComponentDataTypeList& list);
331   
332   const AliHLTComponentEventData* fEventData; //! Event data for the current event. Only valid inside DoTrigger.
333   AliHLTComponentTriggerData* fTriggerData; //! Trigger data for the current event. Only valid inside DoTrigger.
334   bool fDecisionMade;  //! Flag indicating if the trigger decision has been made for this trigger yet.
335   bool fClearInfo;  //! Flag indicating if fDescription, fReadoutList and fTriggerDomain should be cleared for each new event.
336   int fTriggerEventResult;  //! Result returned by PushBack method in the TriggerEvent method.
337   TString fDescription;   //! The description to use for the trigger decision.
338   AliHLTReadoutList fReadoutList; //! The DDL readout list object for the current event being processed.
339   AliHLTTriggerDomain fTriggerDomain; //! The trigger domain object for the current event being processed.
340   AliHLTUInt32_t fReadoutListSpecBits;  //! Readout list data block specification bits used when generating the data block.
341   
342   ClassDef(AliHLTTrigger, 0) // Base class for HLT triggers.
343
344 };
345
346 #endif // ALIHLTTRIGGER_H
347