Update for complying with train (first round)
[u/mrichter/AliRoot.git] / HLT / BASE / util / AliHLTFileWriter.h
1 // @(#) $Id$
2
3 #ifndef ALIHLTFILEWRITER_H
4 #define ALIHLTFILEWRITER_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   AliHLTFileWriter.h
10     @author Matthias Richter
11     @date   
12     @brief  An HLT file dump (data sink) component.
13 */
14
15 #include "AliHLTDataSink.h"
16 #include <TString.h>
17
18 /**
19  * @class AliHLTFileWriter
20  * An HLT data sink component which writes data to file(s).
21  *
22  * <h2>General properties:</h2>
23  *
24  * Component ID: \b FileWriter      <br>
25  * Library: \b libAliHLTUtil.so     <br>
26  * Input Data Types: @ref kAliHLTAllDataTypes <br>
27  * Output Data Types: none <br>
28  *
29  * kAliHLTAllDataTypes contains both kAliHLTAnyDataType and kAliHLTVoidDataType
30  *
31  * <h2>Mandatory arguments:</h2>
32  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
33  *
34  * <h2>Optional arguments:</h2>
35  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
36  * \li -datafile     <i> filename   </i> <br>
37  *      file name base
38  * \li -directory    <i> directory  </i> <br>
39  *      target directory
40  * \li -subdir[=pattern] <br>
41  *      create sub dir for each event, the format pattern can contain printf
42  *      specifiers to print the event no into the dir name, default is
43  *      'event%03d' (-subdir w/o additional pattern)
44  *      \b note: the idfmt string is reset since the subdir contains the id
45  * \li -idfmt[=pattern] <br>
46  *      format specifier for the event id in the file name,                <br>
47  *      default: on, default pattern: '_0x%08x'
48  * \li -specfmt[=pattern] <br>
49  *      format specifier for the data specification in the file name       <br>
50  *      default: off, default pattern: '_0x%08x'
51  * \li -blocknofmt[=pattern] <br>
52  *      format specifier for the block no in the file name                 <br>
53  *      default: on, default pattern: '_0x%02x'
54  * \li -enumerate <br>
55  *      don't use the event number but an event counter beginning from 0
56  * \li -concatenate-blocks <br>
57  *      concatenate all blocks of one event into one file, this skips
58  *      the block no, and the block data type in the file name
59  * \li -concatenate-events <br>
60  *      concatenate all events into one file, this skips the event no,
61  *      the block no, and the block data type in the file name. Currently,
62  *      this implies the -concatenate-blocks option.
63  *
64  * <h2>Configuration:</h2>
65  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
66  * no configuration
67  *
68  * <h2>Default CDB entries:</h2>
69  * The component loads no CDB entries.
70  *
71  * <h2>Performance:</h2>
72  * The component does not any event data processing.
73  *
74  * <h2>Memory consumption:</h2>
75  * The component does not any event data processing.
76  *
77  * <h2>Output size:</h2>
78  * The component has no output data.
79  *
80  *
81  * By default, file name is built from the basename, the event number, the
82  * block number and the data type in the format:
83  * <pre>
84  * basename_eventno_dt
85  * </pre>
86  * If the basename was not given, \em 'event' ist used instead. A file
87  * extension after the last dot is separated from the basename and appended
88  * to the final name.
89  *
90  * The naming rule can be changed by the -xxfmt options, which can contain
91  * printf format specifiers in order to print the corresponding variable. E.g.
92  * <pre>
93  * -specfmt             append specification
94  * -subdir=test_%d      store in sub folders
95  * -blocknofmt=_0x%x    format block no in hex
96  * -idfmt=_%04d         print id in 4-digits decimal number
97  * -idfmt=              print no id
98  * </pre>
99  *
100  * The class can be used as a base class for file writers. Additional
101  * argument scan can be implemented in @ref ScanArgument which is called
102  * for each unknown argument.
103  * @ingroup alihlt_component
104  */
105 class AliHLTFileWriter : public AliHLTDataSink  {
106  public:
107   /** standard constructor */
108   AliHLTFileWriter();
109   /** destructor */
110   virtual ~AliHLTFileWriter();
111
112   virtual const char* GetComponentID();
113   virtual void GetInputDataTypes( vector<AliHLTComponentDataType>& list);
114   virtual AliHLTComponent* Spawn();
115
116  protected:
117   /**
118    * Init method.
119    */
120   int DoInit( int argc, const char** argv );
121
122   /**
123    * Deinit method.
124    */
125   int DoDeinit();
126
127   /**
128    * Init the writer.
129    * The DoInit function is not available for child classes. InitWriter is the
130    * corresponding function for classes derived from AliHLTFileWriter.
131    */
132   virtual int InitWriter();
133
134   /**
135    * Close the writer.
136    * The DoDeinit function is not available for child classes. CloseWriter is the
137    * corresponding function for classes derived from AliHLTFileWriter.
138    */
139   virtual int CloseWriter();
140
141   /**
142    * Data processing method for the component.
143    * The function can be overloaded by other file writer components.
144    * @param evtData       event data structure
145    * @param trigData      trigger data structure
146    */
147   virtual int DumpEvent( const AliHLTComponentEventData& evtData,
148                          AliHLTComponentTriggerData& trigData );
149
150   using AliHLTDataSink::DumpEvent;
151
152   /**
153    * Scan one argument and adjacent parameters.
154    * Can be overloaded by child classes in order to add additional arguments
155    * beyond the standard arguments of the file publisher. The method is called
156    * whenever a non-standard argument is recognized. Make sure to return 
157    * <tt> -EPROTO </tt> if the argument is not recognized be the child.
158    * @param argc           size of the argument array
159    * @param argv           agument array for component initialization
160    * @return number of processed members of the argv <br>
161    *         -EINVAL unknown argument <br>
162    *         -EPROTO parameter for argument missing <br>
163    */
164   virtual int ScanArgument(int argc, const char** argv);
165
166   /**
167    * Build file name from eventID data type and the specified directory and basename.
168    * @param eventID [in]   the ID of the event
169    * @param blockID [in]   the ID of the current block
170    *                       no block string appended if -1
171    * @param dataType [in]  the data type of the data block
172    *                       no type string appanded if @ref kAliHLTVoidDataType
173    * @param specification  data specification of the block
174    * @param filename [out] string to receive the file name
175    */
176   int BuildFileName(const AliHLTEventID_t eventID, const int blockID,
177                     const AliHLTComponentDataType& dataType,
178                     const AliHLTUInt32_t specification,
179                     TString& filename);
180
181   /**
182    * Set a mode flag.
183    * @return current mode flags
184    */
185   int SetMode(Short_t mode);
186     
187   /**
188    * Clear a mode flag.
189    * @return current mode flags
190    */
191   int ClearMode(Short_t mode);
192
193   /**
194    * Check a mode flag.
195    * @return 1 if flag is set, 0 if not
196    */
197   int CheckMode(Short_t mode) const;
198
199   /**
200    * Get the currently set file extension.
201    */
202   TString GetExtension() {return fExtension;}
203
204   /**
205    * Set the file extension.
206    */
207   void SetExtension(const char* extension) {fExtension=extension!=NULL?extension:"";}
208
209   /**
210    * Working modes of the writer
211    * @internal
212    */
213   enum TWriterMode {
214     /**
215      * flag to indicate whether to write each incoming block to separate files
216      * or all blocks of one event to one file. set = concatenate (one file).
217      */
218     kConcatenateBlocks = 0x1,
219
220     /**
221      * flag to indicate whether to concatenate incoming blocks of the same type
222      * for all events to one file. If also @ref kConcatenateBlocks is set,
223      * or all blocks of all events are written to the same file.
224      */
225     kConcatenateEvents = 0x2,
226
227     /** event enumeration flag */
228     kEnumerate = 0x4
229
230   };
231
232  private:
233   /** copy constructor prohibited */
234   AliHLTFileWriter(const AliHLTFileWriter&);
235   /** assignment operator prohibited */
236   AliHLTFileWriter& operator=(const AliHLTFileWriter&);
237
238   /** the basename of the output file */
239   TString    fBaseName;                                            // see above
240   /** the extension of the output file */
241   TString    fExtension;                                           // see above
242   /** target directory */
243   TString    fDirectory;                                           // see above
244   /** base name of the event sub directories */
245   TString    fSubDirFormat;                                        // see above
246   /** event id format string (when added to file name) */
247   TString    fIdFormat;                                            // see above
248   /** specification format string (when added to file name) */
249   TString    fSpecFormat;                                          // see above
250   /** format string for block no (when added to file name) */
251   TString    fBlcknoFormat;                                        // see above
252  protected:
253   /** enumeration format string */
254   TString    fCurrentFileName;                                     // see above
255  private:
256
257   /** mode specifier, see @ref TWriterMode */
258   Short_t    fMode;                                                // see above
259
260   ClassDef(AliHLTFileWriter, 2)
261 };
262 #endif