HLT/BASE/util/AliHLTFileWriter.h

   1 // -*- Mode: C++ -*-
   2 // $Id$
   3
   4 #ifndef ALIHLTFILEWRITER_H
   5 #define ALIHLTFILEWRITER_H
   6 //* This file is property of and copyright by the ALICE HLT Project        *
   7 //* ALICE Experiment at CERN, All rights reserved.                         *
   8 //* See cxx source for full Copyright notice                               *
   9
  10 /** @file   AliHLTFileWriter.h
  11     @author Matthias Richter
  12     @date
  13     @brief  An HLT file dump (data sink) component.
  14 */
  15
  16 #include "AliHLTDataSink.h"
  17 #include <TString.h>
  18
  19 class AliHLTBlockDataCollection;
  20
  21 /**
  22  * @class AliHLTFileWriter
  23  * An HLT data sink component which writes data to file(s).
  24  *
  25  * <h2>General properties:</h2>
  26  *
  27  * Component ID: \b FileWriter      <br>
  28  * Library: \b libAliHLTUtil.so     <br>
  29  * Input Data Types: ::kAliHLTAllDataTypes <br>
  30  * Output Data Types: none <br>
  31  *
  32  * \b Note: ::kAliHLTAllDataTypes contains both ::kAliHLTAnyDataType and
  33  * ::kAliHLTVoidDataType
  34  *
  35  * <h2>Mandatory arguments:</h2>
  36  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
  37  *
  38  * <h2>Optional arguments:</h2>
  39  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
  40  * \li -datafile     <i> filename   </i> <br>
  41  *      file name base
  42  * \li -directory    <i> directory  </i> <br>
  43  *      target directory
  44  * \li -subdir[=pattern] <br>
  45  *      create sub dir for each event, the format pattern can contain printf
  46  *      specifiers to print the event no into the dir name, default is
  47  *      'event%%03lu' (-subdir w/o additional pattern). The format specifyer
  48  *      %%lu is automatically added if missing in the pattern. Please note the
  49  *      \b long int type of the event id                                   <br>
  50  *      \b note: the idfmt string is reset since the subdir contains the id
  51  * \li -idfmt[=pattern] <br>
  52  *      format specifier for the event id in the file name,                <br>
  53  *      default: on, default pattern: '_0x%%08x'
  54  * \li -specfmt[=pattern] <br>
  55  *      format specifier for the data specification in the file name       <br>
  56  *      default: off, default pattern: '_0x%%08x'
  57  * \li -blocknofmt[=pattern] <br>
  58  *      format specifier for the block no in the file name                 <br>
  59  *      default: on, default pattern: '_0x%%02x'
  60  * \li -skip-datatype <br>
  61  *      do not consider data type when building the file name.
  62  * \li -enumerate <br>
  63  *      don't use the event number but an event counter beginning from 0
  64  * \li -concatenate-blocks <br>
  65  *      concatenate all blocks of one event into one file, this skips
  66  *      the block no, and the block data type in the file name
  67  * \li -concatenate-events <br>
  68  *      concatenate all events into one file, this skips the event no,
  69  *      the block no, and the block data type in the file name. Currently,
  70  *      this implies the -concatenate-blocks option.
  71  * \li -publisher-conf <i>filename</i> <br>
  72  *      write configuration file for FilePublisher component (AliHLTFilePublisher) <br>
  73  *      one line per file: -datatype id origin -datafile filename           <br>
  74  *      events separated by -nextevent
  75  * \li -write-all-events <br>
  76  *      by default, the file writer ignores all steering events like the
  77  *      the SOR/EOR events, with this option, all events will be considered
  78  *      the beginning.
  79  * \li -write-all-blocks <br>
  80  *      by default, the file writer ignores all blocks of origin {PRIV}
  81  *      (::kAliHLTDataOriginPrivate), with this option, all blocks will
  82  *      be written. For SOR/EOR events, a short string will be added in
  83  *      the beginning.
  84  * \li -write-all <br>
  85  *      combines both -write-all-events and -write-all-blocks
  86  * \li -burst-buffer <size> <br>
  87  *      size of burst buffer, blocks are written to buffer until it is filled
  88  *      and written in one burst (though to different files according to conf)<br>
  89  *      \b Note: burst write is currently only supported for mode
  90  *      -concatenate-events AND -concatenate-blocks (both enabled).
  91  * \li -datatype     <i> id origin      </i>                            <br>
  92  *     data block selection by AliHLTBlockDataCollection
  93  * \li -origin  <i> origin  </i>                                        <br>
  94  *     data block selection by AliHLTBlockDataCollection
  95  * \li -typeid  <i> id      </i>                                        <br>
  96  *     data block selection by AliHLTBlockDataCollection
  97  * \li -dataspec     <i> specification </i>                             <br>
  98  *     data block selection by AliHLTBlockDataCollection
  99  *
 100  * <h2>Configuration:</h2>
 101  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
 102  * Configuration by component arguments.
 103  *
 104  * <h2>Default CDB entries:</h2>
 105  * The component loads no CDB entries.
 106  *
 107  * <h2>Performance:</h2>
 108  * The component does not process any event data.
 109  *
 110  * <h2>Memory consumption:</h2>
 111  * The component does not process any event data.
 112  *
 113  * <h2>Output size:</h2>
 114  * No data published (AliHLTDataSink).
 115  *
 116  *
 117  * By default, file name is built from the basename, the event number, the
 118  * block number and the data type in the format:
 119  * <pre>
 120  * basename_eventno_dt
 121  * </pre>
 122  * If the basename was not given, \em 'event' ist used instead. A file
 123  * extension after the last dot is separated from the basename and appended
 124  * to the final name.
 125  *
 126  * The naming rule can be changed by the -xxfmt options, which can contain
 127  * printf format specifiers in order to print the corresponding variable. E.g.
 128  * <pre>
 129  * -specfmt             append specification
 130  * -subdir=test         store in sub folders
 131  * -blocknofmt=_0x%%x   format block no in hex
 132  * -idfmt=_%%04d        print id in 4-digits decimal number
 133  * -idfmt=              print no id
 134  * </pre>
 135  *
 136  * The class can be used as a base class for file writers. Additional
 137  * argument scan can be implemented in @ref ScanArgument which is called
 138  * for each unknown argument.
 139  *
 140  * @ingroup alihlt_util_components
 141  */
 142 class AliHLTFileWriter : public AliHLTDataSink  {
 143  public:
 144   /** standard constructor */
 145   AliHLTFileWriter();
 146   /** destructor */
 147   virtual ~AliHLTFileWriter();
 148
 149   virtual const char* GetComponentID();
 150   virtual void GetInputDataTypes( vector<AliHLTComponentDataType>& list);
 151   virtual AliHLTComponent* Spawn();
 152
 153  protected:
 154   /**
 155    * Init method.
 156    */
 157   int DoInit( int argc, const char** argv );
 158
 159   /**
 160    * Deinit method.
 161    */
 162   int DoDeinit();
 163
 164   /**
 165    * Init the writer.
 166    * The DoInit function is not available for child classes. InitWriter is the
 167    * corresponding function for classes derived from AliHLTFileWriter.
 168    */
 169   virtual int InitWriter();
 170
 171   /**
 172    * Close the writer.
 173    * The DoDeinit function is not available for child classes. CloseWriter is the
 174    * corresponding function for classes derived from AliHLTFileWriter.
 175    */
 176   virtual int CloseWriter();
 177
 178   /**
 179    * Data processing method for the component.
 180    * The function can be overloaded by other file writer components.
 181    * @param evtData       event data structure
 182    * @param trigData      trigger data structure
 183    */
 184   virtual int DumpEvent( const AliHLTComponentEventData& evtData,
 185                          AliHLTComponentTriggerData& trigData );
 186
 187   using AliHLTDataSink::DumpEvent;
 188
 189   /**
 190    * Scan one argument and adjacent parameters.
 191    * Can be overloaded by child classes in order to add additional arguments
 192    * beyond the standard arguments of the file publisher. The method is called
 193    * whenever a non-standard argument is recognized. Make sure to return
 194    * <tt> -EPROTO </tt> if the argument is not recognized be the child.
 195    * @param argc           size of the argument array
 196    * @param argv           agument array for component initialization
 197    * @return number of processed members of the argv <br>
 198    *         -EINVAL unknown argument <br>
 199    *         -EPROTO parameter for argument missing <br>
 200    */
 201   virtual int ScanArgument(int argc, const char** argv);
 202
 203   /**
 204    * Build file name from eventID data type and the specified directory and basename.
 205    * @param [in] eventID   the ID of the event
 206    * @param [in] blockID   the ID of the current block
 207    *                       no block string appended if -1
 208    * @param [in] dataType  the data type of the data block
 209    *                       no type string appanded if @ref kAliHLTVoidDataType
 210    * @param [in] specification  data specification of the block
 211    * @param [out] filename string to receive the file name
 212    */
 213   int BuildFileName(const AliHLTEventID_t eventID, const int blockID,
 214                     const AliHLTComponentDataType& dataType,
 215                     const AliHLTUInt32_t specification,
 216                     TString& filename);
 217
 218   /**
 219    * Set a mode flag.
 220    * @return current mode flags
 221    */
 222   int SetMode(Short_t mode);
 223
 224   /**
 225    * Clear a mode flag.
 226    * @return current mode flags
 227    */
 228   int ClearMode(Short_t mode);
 229
 230   /**
 231    * Check a mode flag.
 232    * @return 1 if flag is set, 0 if not
 233    */
 234   int CheckMode(Short_t mode) const;
 235
 236   /**
 237    * Get the currently set file extension.
 238    */
 239   TString GetExtension() {return fExtension;}
 240
 241   /**
 242    * Set the file extension.
 243    */
 244   void SetExtension(const char* extension) {fExtension=extension!=NULL?extension:"";}
 245
 246   /**
 247    * Get the target directory
 248    */
 249   TString GetDirectory() {return fDirectory;}
 250
 251   /**
 252    * Working modes of the writer
 253    * @internal
 254    */
 255   enum TWriterMode {
 256     /**
 257      * flag to indicate whether to write each incoming block to separate files
 258      * or all blocks of one event to one file. set = concatenate (one file).
 259      */
 260     kConcatenateBlocks = 0x1,
 261
 262     /**
 263      * flag to indicate whether to concatenate incoming blocks of the same type
 264      * for all events to one file. If also @ref kConcatenateBlocks is set,
 265      * or all blocks of all events are written to the same file.
 266      */
 267     kConcatenateEvents = 0x2,
 268
 269     /** event enumeration flag */
 270     kEnumerate = 0x4,
 271
 272     /** write all events including steering events */
 273     kWriteAllEvents = 0x8,
 274
 275     /** write all blocks including private ones */
 276     kWriteAllBlocks = 0x10,
 277
 278     /** skip the data type information when creating the file name */
 279     kSkipDataType = 0x20
 280   };
 281
 282   /** argument scan concerning block descriptor selections */
 283   AliHLTBlockDataCollection* fpBlockDataCollection;                //!transient
 284
 285  private:
 286   /** copy constructor prohibited */
 287   AliHLTFileWriter(const AliHLTFileWriter&);
 288   /** assignment operator prohibited */
 289   AliHLTFileWriter& operator=(const AliHLTFileWriter&);
 290
 291   /**
 292    * Set defaults for all internal properties
 293    */
 294   int SetDefaults();
 295
 296   /**
 297    * Schedule block for writing.
 298    * The block is written immediately unless burst mode is activated.
 299    * In burst mode, the block is buffered in the burst buffer until it is filled.
 300    * Content of the burst buffer is then written in one burst.
 301    *
 302    * In the first implementation, burst write is only foreseen for the base
 303    * file writer.
 304    */
 305   int ScheduleBlock(int blockno, const AliHLTEventID_t& eventID,
 306                     const AliHLTComponentBlockData* pDesc);
 307
 308   /**
 309    * Flush burst buffer.
 310    */
 311   int BurstWrite();
 312
 313   /**
 314    * Write data block;
 315    * Build file name from the block attributes and compare with the
 316    * lat file name in order to correctly append data or not.
 317    */
 318   int WriteBlock(int blockno, const AliHLTEventID_t& eventID,
 319                  const AliHLTComponentBlockData* pDesc);
 320
 321   /** the basename of the output file */
 322   TString    fBaseName;                                            // see above
 323   /** the extension of the output file */
 324   TString    fExtension;                                           // see above
 325   /** target directory */
 326   TString    fDirectory;                                           // see above
 327   /** base name of the event sub directories */
 328   TString    fSubDirFormat;                                        // see above
 329   /** event id format string (when added to file name) */
 330   TString    fIdFormat;                                            // see above
 331   /** specification format string (when added to file name) */
 332   TString    fSpecFormat;                                          // see above
 333   /** format string for block no (when added to file name) */
 334   TString    fBlcknoFormat;                                        // see above
 335  protected:
 336   /** enumeration format string */
 337   TString    fCurrentFileName;                                     // see above
 338  private:
 339
 340   /** mode specifier, see @ref TWriterMode */
 341   Short_t    fMode;                                                // see above
 342
 343   /** burst buffer for postponed data write */
 344   AliHLTUInt8_t* fpBurstBuffer;                                    //!transient
 345
 346   /** size of burst buffer */
 347   AliHLTUInt32_t fBurstBufferSize;                                 //!transient
 348
 349   /** block descriptor list for postponed burst write*/
 350   AliHLTComponentBlockDataList fBurstBlocks;                       //!transient
 351
 352   /** event ids for the burst blocks */
 353   vector<AliHLTEventID_t> fBurstBlockEvents;                       //!transient
 354
 355   /// configuration file of FilePublisher component
 356   TString fPublisherConfName;                                      // see above
 357   /// current event for FilePublisher configuration
 358   int fPublisherConfEvent;                                         // see above
 359
 360   ClassDef(AliHLTFileWriter, 0)
 361 };
 362 #endif