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