source: proiecte/hpl/openmpi_compiled/include/vampirtrace/OTF_Writer.h @ 97

/*
 This is part of the OTF library. Copyright by ZIH, TU Dresden 2005-2008.
 Authors: Andreas Knuepfer, Holger Brunst, Ronny Brendel, Thomas Kriebitzsch
*/

/** 
 *  @file OTF_Writer.h
 *
 *  @brief Transparently writes OTF traces which consist of multiple streams.
 *
 * \ingroup writer
 */

/** \defgroup writer Writer Interface
 *
 *  This interface should be used whenever a trace file is to be written as a
 *  whole.  Therefore, an initial call to the OTF_Writer_open() function
 *  allows to specify a number of streams which are going to be used to
 *  automatically partition the recorded event data. OTF than takes over the
 *  duty of distributing the data on multiple files.
 *
 *  \section writer_example A simple Example
 *
 *  \code
 *  #include <assert.h>
 *  #include "otf.h"
 *
 *  int main( int argc, char** argv ) {
 *  \endcode
 *
 *      Declare a file manager and a writer.
 *      \code
 *          OTF_FileManager* manager;
 *          OTF_Writer* writer;
 *          \endcode
 *
 *      Initialize the file manager. Open at most 100 OS files.
 *      \code
 *      manager= OTF_FileManager_open( 100 );
 *          assert( manager );
 *          \endcode
 *
 *          Initialize the writer. Open file "test", writing one stream.
 *          \code
 *          writer = OTF_Writer_open( "test", 1, manager );
 *      assert( writer );
 *      \endcode
 *      
 *      Write some important Definition Records.
 *      Have a look at the specific functions to see what the parameters mean.
 *      \code
 *      OTF_Writer_writeDefTimerResolution( writer, 0, 1000 );
 *      OTF_Writer_writeDefProcess( writer, 0, 1, "proc one", 0 );
 *      OTF_Writer_writeDefFunctionGroup( writer, 0, 1000, "all functions" );
 *      OTF_Writer_writeDefFunction( writer, 0, 1, "main", 1000, 0 );
 *      \endcode
 *
 *
 *      Write an enter and a leave record.
 *      time = 10000, 20000
 *      process = 1
 *      function = 1
 *      Sourcecode location doesn't matter, so it's zero.
 *      \code
 *      OTF_Writer_writeEnter( writer, 10000, 1, 1, 0 );
 *      OTF_Writer_writeLeave( writer, 20000, 1, 1, 0 );
 *      \endcode
 *
 *      Clean up before exiting the program.
 *      \code
 *      OTF_Writer_close( writer );
 *      OTF_FileManager_close( manager );
 *
 *              return 0;
 * }
 * \endcode
 *
 * Compile this using $ gcc -o test test.c `otfconfig --libs`.
 *
 */

#ifndef OTF_WRITER_H
#define OTF_WRITER_H


#include "OTF_MasterControl.h"
#include "OTF_FileManager.h"
#include "OTF_WBuffer.h"
#include "OTF_WStream.h"


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/** writer object \ingroup writer */
typedef struct struct_OTF_Writer OTF_Writer;

/* *** public member functions *** */


/**     
 * Create a new OTF_Writer instance with a given number of automatic streams.
 *
 * Setting the number of streams to 0 causes the OTF_Writer object to create a
 * separate stream for each process. Important! Explicit calls to
 * OTF_Writer_assignProcess() can lead to an overall number of streams which
 * exceeds the initial number of streams in this call. 
 * OTF can reduce its file handle usage to a given number. Therefore, an 
 * initialized file manager instance is needed as parameter. 
 * See OTF_FileManager for further details.
 *
 * @param  fileNamePrefix   File name prefix which is going to be used by 
 *                          all sub-files which belong to the trace.
 * @param  numberOfStreams  Initial number of independent data streams to 
 *                          be generated.
 * @param  fileManager      File handle manager. 
 *
 *
 * @return                  Initialized OTF_Writer instance or 0 if a failure
 *                          occurred.
 *
 * \ingroup writer
 */
OTF_Writer* OTF_Writer_open( const char* fileNamePrefix, 
                             uint32_t numberOfStreams, 
                             OTF_FileManager* fileManager );


/** 
 * Close an OTF_Writer instance and all its related files.
 *
 * @param writer  Pointer to an initialized OTF_Writer object. See 
 *                also OTF_Writer_open().
 * 
 * @return        1 if instance was closed successfully and 0 otherwise.       
 *
 * \ingroup writer
 */
int OTF_Writer_close( OTF_Writer* writer );


/** 
 * Close all streams that are open in this writer instance.
 *
 * @param writer  Pointer to an initialized OTF_Writer object. See 
 *                also OTF_Writer_open().
 *
 * @return        1 on success, 0 if an error occurs.
 * 
 * \ingroup writer
 */
int OTF_Writer_closeAllStreams( OTF_Writer* writer );


/**
 * Set the standard compression method for all buffers managed by this writer
 *
 * @param writer       Pointer to an initialized OTF_Writer object. See 
 *                     also OTF_Writer_open().
 *
 * @param compression  compression level to apply to all following streams
 *                     0-9, where 0 means no compression is applied, and 9 is
 *                     the highest level of compression.
 *
 * @return             1 on success, 0 if an error occurs.
 *
 * \ingroup writer
 */
int OTF_Writer_setCompression( OTF_Writer* writer, OTF_FileCompression
        compression );

        
/**
 * Return the standard compression method for all buffers managed by this writer
 *
 * @param writer       Pointer to an initialized OTF_Writer object. See 
 *                     also OTF_Writer_open().
 *
 * @return             Standard compression level for all buffers managed by
 *                     this writer.
 *
 * \ingroup writer
 */
OTF_FileCompression OTF_Writer_getCompression( OTF_Writer* writer );


/**
 * Set the default buffer size for all buffers managed by this Writer. 
 * This is only effective for future buffers and will not change already 
 * allocated buffers. Those can be changed with the buffers directly.
 *
 * @param writer  Pointer to an initialized OTF_Writer object. See 
 *                also OTF_Writer_open().
 * 
 * @param size    Intended buffer size.
 *
 * \ingroup writer
 */
void OTF_Writer_setBufferSizes( OTF_Writer* writer, uint32_t size );


/** 
 * Get the default buffer size for all buffers managed by this Writer.
 *
 * @param writer  Pointer to an initialized OTF_Writer object. See 
 *                also OTF_Writer_open().
 * 
 * @return        Default buffer size for all buffers managed by this Writer.
 *
 * \ingroup writer
 */
uint32_t OTF_Writer_getBufferSizes( OTF_Writer* writer );


/**
 * Set the default zbuffer size for all buffers managed by this Reader.
 * This is only effective for future files and will not change already
 * allocated zbuffers. Those can be changed with the files directly.
 *
 * @param writer  Pointer to an initialized OTF_Writer object. See 
 *                also OTF_Writer_open().
 *
 * @param size    Intended zbuffer size.
 *
 * \ingroup writer
 */
void OTF_Writer_setZBufferSizes( OTF_Writer* writer, uint32_t size );

/** 
 * Get the default zbuffer size.
 *
 * @param writer  Pointer to an initialized OTF_Writer object. See 
 *                also OTF_Writer_open().
 *
 * @return  zbuffer size.
 *
 * \ingroup writer
 */
uint32_t OTF_Writer_getZBufferSizes( OTF_Writer* writer );

/**
 * Set the default ouput format. The format is applied to all streams opened by
 * the writer.
 *
 * @param writer  Pointer to an initialized OTF_Writer object. See 
 *                also OTF_Writer_open().
 *
 * @param format  Intended output format (OTF_WSTREAM_FORMAT_{LONG,SHORT}).
 *
 * \ingroup writer
 */
void OTF_Writer_setFormat( OTF_Writer* writer, uint32_t format );


/**
 * Get the default output format of all streams managed by this writer.
 *
 * @param writer  Pointer to an initialized OTF_Writer object. See 
 *                also OTF_Writer_open().
 *
 * @return        Default output format.
 *
 * \ingroup writer
 */
uint32_t OTF_Writer_getFormat( OTF_Writer* writer );


/**     
 * Explicitly assign a given process to a specific stream.
 *
 * Mind that 0 is not a valid stream or process identifier but a reserved
 * value. By default, processes are automatically assigned to streams.
 * Therefore, this call is optional. 
 * 
 * @param writer   Pointer to an initialized OTF_Writer object. See 
 *                 also OTF_Writer_open().
 * @param process  Process identifier. See also OTF_Writer_writeDefProcess().
 * @param stream   Target stream identifier with 
 *                 0 < stream <= number of streams as defined in 
 *                 OTF_Writer_open().
 *
 * @return         1 on success, 0 if an error occurs. 
 *
 * \ingroup writer
 */
uint32_t OTF_Writer_assignProcess( OTF_Writer* writer,
                                   uint32_t process, 
                                   uint32_t stream );


/**
 * Get a pointer to the master control object of the given writer instance.
 *
 * @param writer   Pointer to an initialized OTF_Writer object. See 
 *                 also OTF_Writer_open().
 *
 * @return         Pointer to a master control object. See OTF_MasterControl.
 *
 * \ingroup writer
 */
OTF_MasterControl* OTF_Writer_getMasterControl( OTF_Writer* writer );


/**
 * Set an alternative master control object. Use this only right after 
 * initialization but never after having written some records already!
 *
 * @param writer   Pointer to an initialized OTF_Writer object. See 
 *                 also OTF_Writer_open().
 * @param mc       new master control object
 *                 
 *
 * \ingroup writer
 */
void OTF_Writer_setMasterControl( OTF_Writer* writer, OTF_MasterControl* mc );


/* Methods for writing public definition records ************************** */


/**
 * Write a comment record.
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param stream    Target stream identifier with 
 *                  0 < stream <= number of streams as defined in 
 *                  OTF_Writer_open().
 * @param comment   Arbitrary comment string.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefinitionComment( OTF_Writer* writer, 
                                       uint32_t stream, 
                                       const char* comment );


/**
 * Write the timer resolution definition record. All timed event records
 * will be interpreted according to this definition. By default, a timer
 * resultion of 1 us i.e. 1,000,000 clock ticks is assumed. 
 *
 * @param writer          Pointer to an initialized OTF_Writer object. See 
 *                        also OTF_Writer_open().
 * @param stream          Target stream identifier with 
 *                        0 < stream <= number of streams as defined in 
 *                        OTF_Writer_open().
 * @param ticksPerSecond  Clock ticks per second of the timer.
 *
 * @return                1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefTimerResolution( OTF_Writer* writer, 
                                        uint32_t stream,
                                        uint64_t ticksPerSecond );


/**
 * Write a process definition record. 
 *
 * @param writer   Pointer to an initialized OTF_Writer object. See 
 *                 also OTF_Writer_open().
 * @param stream   Target stream identifier with 
 *                 0 < stream <= number of streams as defined in 
 *                 OTF_Writer_open().
 * @param process  Arbitrary but unique process identifier > 0.        
 * @param name     Name of the process e.g. "Process X".
 * @param parent   Previously declared parent process identifier or 0 if 
 *                 process has no parent.
 *
 * @return         1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefProcess( OTF_Writer* writer, 
                                uint32_t stream,
                                uint32_t process, 
                                const char* name, 
                                uint32_t parent );


/**
 * Write a process group definition record.
 *
 * OTF supports groups of processes. Their main objective is to classify
 * processes depending on arbitrary characteristics. Processes can reside
 * in multiple groups. This record type is optional.
 *
 * @param writer         Pointer to an initialized OTF_Writer object. See 
 *                       also OTF_Writer_open().
 * @param stream         Target stream identifier with 
 *                       0 < stream <= number of streams as defined in 
 *                       OTF_Writer_open().
 * @param procGroup      Arbitrary but unique process group identifier > 0.
 * @param name           Name of the process group e.g. "Well Balanced".
 * @param numberOfProcs  The number of processes in the process group.
 * @param procs          Vector of process identifiers or previously defined
 *                       process group identifiers as defined with
 *                       OTF_Writer_writeDefProcess() resp. 
 *                       OTF_Writer_writeDefProcessGroup.
 *
 * @return               1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefProcessGroup( OTF_Writer* writer, 
                                     uint32_t stream,
                                     uint32_t procGroup, 
                                     const char* name, 
                                     uint32_t numberOfProcs, 
                                     const uint32_t* procs );


/**
 * Write a function definition record.
 *
 * Defines a function of the given name. Functions can optionally belong to a
 * certain function group to be defined with the
 * OTF_Writer_writeDefFunctionGroup() call. A source code reference can
 * be added to the definition aswell.
 *
 * @param writer     Pointer to an initialized OTF_Writer object. See 
 *                   also OTF_Writer_open().
 * @param stream     Target stream identifier with 
 *                   0 < stream <= number of streams as defined in 
 *                   OTF_Writer_open().
 * @param func       Arbitrary but unique function identifier > 0.
 * @param name       Name of the function e.g. "DoSomething".
 * @param funcGroup  A function group identifier preliminary defined with
 *                   OTF_Writer_writeDefFunctionGroup() or 0 for no
 *                   function group assignment.        
 * @param source     Reference to the function's source code location 
 *                   preliminary defined with OTF_Writer_writeDefScl() or
 *                   0 for no source code location assignment.
 *
 * @return           1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefFunction( OTF_Writer* writer, 
                                 uint32_t stream,
                                 uint32_t func, 
                                 const char* name, 
                                 uint32_t funcGroup, 
                                 uint32_t source );


/**
 * Write a function group definition record.
 *
 * @param writer     Pointer to an initialized OTF_Writer object. See 
 *                   also OTF_Writer_open().
 * @param stream     Target stream identifier with 
 *                   0 < stream <= number of streams as defined in 
 *                   OTF_Writer_open().
 * @param funcGroup  An arbitrary but unique function group identifier > 0.
 * @param name       Name of the function group e.g. "Computation".
 *
 * @return           1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefFunctionGroup( OTF_Writer* writer, 
                                      uint32_t stream,
                                      uint32_t funcGroup, 
                                      const char* name );


/**
 * Write a collective operation definition record.
 *
 * @param writer      Initialized OTF_Writer instance.
 * @param stream      Target stream identifier with 
 *                    0 < stream <= number of streams as defined in 
 *                    OTF_Writer_open().
 * @param collOp      An arbitrary but unique collective op. identifier > 0.
 * @param name        Name of the collective operation e.g. "MPI_Bcast".
 * @param type        One of the five supported collective classes:
 *                    OTF_COLLECTIVE_TYPE_UNKNOWN (default),
 *                    OTF_COLLECTIVE_TYPE_BARRIER,
 *                    OTF_COLLECTIVE_TYPE_ONE2ALL,
 *                    OTF_COLLECTIVE_TYPE_ALL2ONE,
 *                    OTF_COLLECTIVE_TYPE_ALL2ALL.
 *
 * @return            1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefCollectiveOperation( OTF_Writer* writer, 
                                            uint32_t stream,
                                            uint32_t collOp,
                                            const char* name,
                                            uint32_t type );


/**
 * Write a counter definition record.
 *
 * @param writer        Initialized OTF_Writer instance.
 * @param stream        Target stream identifier with 
 *                      0 < stream <= number of streams as defined in 
 *                      OTF_Writer_open().
 * @param counter       An arbitrary but unique counter identifier.
 * @param name          Name of the counter e.g. "Cache Misses".
 * @param properties    A combination of a type and scope counter property.
 *                      OTF_COUNTER_TYPE_ACC (default) represents a counter
 *                      with monotonously increasing values e.g. a FLOP 
 *                      counter. OTF_COUNTER_TYPE_ABS on the other hand 
 *                      defines a counter with alternating absolute values e.g.
 *                      the memory usage of a process. The following counter
 *                      measurement scopes are supported: 
 *                      OTF_COUNTER_SCOPE_START (default) always refers to the 
 *                      start of the process, OTF_COUNTER_SCOPE_POINT refers
 *                      to exactly this moment in time, OTF_COUNTER_SCOPE_LAST
 *                      relates to the previous measurement, and
 *                      OTF_COUNTER_SCOPE_NEXT to the next measurement.
 *                      Examples: OTF_COUNTER_TYPE_ACC + 
 *                      OTF_COUNTER_SCOPE_START should be used for most 
 *                      standard hardware (PAPI) counters. 
 *                      OTF_COUNTER_TYPE_ABS + OTF_COUNTER_SCOPE_POINT could
 *                      be used to record information 'spikes'.
 *                      OTF_COUNTER_TYPE_ABS + OTF_COUNTER_SCOPE_NEXT works
 *                      for memory allocation recording. 
 * @param counterGroup  A previously defined counter group identifier or 0 
 *                      for no group.
 * @param unit          Unit of the counter e.g. "#" for "number of..." or 0 
 *                      for no unit. 
 *
 * @return              1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefCounter( OTF_Writer* writer,
                                uint32_t stream,
                                uint32_t counter,
                                const char* name,
                                uint32_t properties, 
                                uint32_t counterGroup, 
                                const char* unit );


/**
 * Write a counter group definition record.
 *
 * @param writer       Initialized OTF_Writer instance.
 * @param stream       Target stream identifier with 
 *                     0 < stream <= number of streams as defined in 
 *                     OTF_Writer_open().
 * @param counterGroup An arbitrary but unique counter group identifier.
 * @param name         Counter group name.
 *
 * @return             1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefCounterGroup( OTF_Writer* writer, 
                                     uint32_t stream,
                                     uint32_t counterGroup, 
                                     const char* name );


/**
 * Write a source code location (SCL) record.
 *
 * @param writer       Initialized OTF_Writer instance.
 * @param stream       Target stream identifier with 
 *                     0 < stream <= number of streams as defined in 
 *                     OTF_Writer_open().
 * @param source       Arbitrary but unique source code location 
 *                     identifier > 0.
 * @param sourceFile   Previously defined source file identifier. See 
 *                     OTF_Writer_writeDefSclFile(). 
 * @param line         Line number.
 *
 * @return             1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefScl( OTF_Writer* writer,
                            uint32_t stream,
                            uint32_t source,
                            uint32_t sourceFile, 
                            uint32_t line );


/**
 * Write a source code location (SCL) file record.
 *
 * @param writer       Initialized OTF_Writer instance.
 * @param stream       Target stream identifier with 
 *                     0 < stream <= number of streams as defined in 
 *                     OTF_Writer_open().
 * @param sourceFile   Arbitrary but unique source code location 
 *                     identifier != 0.
 * @param name         File name. 
 *
 * @return             1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefSclFile( OTF_Writer* writer,
                                uint32_t stream, 
                                uint32_t sourceFile,
                                const char* name );


/**
 * depricated. The Otf-Version-record is generated automatically at beginning of
 * tracing in the global definiton stream.
 *
 * \ingroup writer
 */
int OTF_Writer_writeOtfVersion( OTF_Writer* writer, uint32_t stream );


/**
 * Write a creator record. 
 *
 * @param writer       Initialized OTF_Writer instance.
 * @param stream       Target stream identifier with 
 *                     0 < stream <= number of streams as defined in 
 *                     OTF_Writer_open().
 * @param creator      String which identifies the creator of the 
 *                     file e.g. "TAU Version x.y.z".
 *
 * @return             1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefCreator( OTF_Writer* writer, uint32_t stream,
                                const char* creator );




/**
 * Write a file definition record
 *
 * @param writer       Initialized OTF_Writer instance.
 * @param stream       Target stream identifier with 
 *                     0 < stream <= number of streams as defined in 
 *                     OTF_Writer_open().
 * @param token        Arbitrary, unique identifier for the file.
 *                     Has to be > 0.
 * @param name         Name of the file.
 * @param group        File group identifier or 0 for no group.
 *
 * @return             1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefFile( OTF_Writer* writer,
                             uint32_t stream,
                             uint32_t token,
                             const char* name,
                             uint32_t group );


/**
 * Write a file group definition record
 *
 * @param writer       Initialized OTF_Writer instance.
 * @param stream       Target stream identifier with 
 *                     0 < stream <= number of streams as defined in 
 *                     OTF_Writer_open().
 * @param token        Arbitrary, unique identifier for the file group.
 *                     Has to be > 0.
 * @param name         Name of the file group.
 *
 * @return             1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeDefFileGroup( OTF_Writer* writer,
                                  uint32_t stream,
                                  uint32_t token,
                                  const char* name );


/**
 * Write a function entry record.
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param time      The time when the function entry took place.
 * @param function  Function to be entered as defined with 
 *                  OTF_Writer_defFunction.
 * @param process   Process where action took place.
 * @param source    Optional reference to source code.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeEnter( OTF_Writer* writer, 
                           uint64_t time, 
                           uint32_t function, 
                           uint32_t process, 
                           uint32_t source );


/**
 * Write a function leave record.
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param time      The time when the function leave took place.
 * @param function  Function which was left or 0 if stack integrety checking
 *                  is not needed.
 * @param process   Process where action took place.
 * @param source    Explicit source code location or 0.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeLeave( OTF_Writer* writer, 
                           uint64_t time, 
                           uint32_t function, 
                           uint32_t process, 
                           uint32_t source );


/**
 * Write a message retrieval record.
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param time      The time when the message was received.
 * @param receiver  Identifier of receiving process.
 * @param sender    Identifier of sending process.
 * @param procGroup Optional process-group sender and receiver belong to,
 *                  '0' for no group.
 * @param tag       Optional message type information.
 * @param length    Optional message length information.
 * @param source    Optional reference to source code.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeRecvMsg( OTF_Writer* writer, 
                             uint64_t time, 
                             uint32_t receiver, 
                             uint32_t sender, 
                             uint32_t procGroup, 
                             uint32_t tag, 
                             uint32_t length, 
                             uint32_t source );


/**
 * Write a message send record.
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param time      The time when the message was send.
 * @param sender    Sender of the message.
 * @param receiver  Receiver of the message.
 * @param procGroup Optional process-group sender and receiver belong to,
 *                  '0' for no group.
 * @param tag       Optional message type information.
 * @param length    Optional message length information.
 * @param source    Optional reference to source code.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeSendMsg( OTF_Writer* writer, 
                             uint64_t time, 
                             uint32_t sender, 
                             uint32_t receiver, 
                             uint32_t procGroup, 
                             uint32_t tag, 
                             uint32_t length, 
                             uint32_t source );


/**
 * Write a counter measurement record.
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param time      Time when counter was measured.
 * @param process   Process where counter measurment took place.
 * @param counter   Counter which was measured. 
 * @param value     Counter value.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeCounter( OTF_Writer* writer, 
                             uint64_t time, 
                             uint32_t process, 
                             uint32_t counter, 
                             uint64_t value );


/**
 * Write a collective operation member record.
 *
 * @param writer      Initialized OTF_Writer instance.
 * @param time        Time when collective operation was entered by member.
 * @param process     Process identifier i.e. collective member. 
 * @param collective  Collective identifier to be defined with
 *                    OTF_Writer_writeDefCollectiveOperation(). 
 * @param procGroup   Group of processes participating in this collective.
 * @param rootProc    Root process if != 0.
 * @param sent        Data volume sent by member or 0.
 * @param received    Data volumd received by member or 0.
 * @param duration    Time spent in collective operation.
 * @param source      Explicit source code location or 0.
 *
 * @return            1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeCollectiveOperation( OTF_Writer* writer, 
                                         uint64_t time, 
                                         uint32_t process, 
                                         uint32_t collective, 
                                         uint32_t procGroup, 
                                         uint32_t rootProc, 
                                         uint32_t sent, 
                                         uint32_t received, 
                                         uint64_t duration, 
                                         uint32_t source );


/**
 * Write a comment record.
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param time      Comments need a timestamp for a proper positioning in the 
 *                  trace.
 * @param process   Comments also need a process identifier for a proper 
 *                  positioning in the trace. 
 * @param comment   Arbitrary comment string.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
 
int OTF_Writer_writeEventComment( OTF_Writer* writer, 
                                  uint64_t time, 
                                  uint32_t process, 
                                  const char* comment );


/**
 * Write a begin process record
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param time      Time when process was referenced for the first time. 
 * @param process   Process identifier > 0.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
 
int OTF_Writer_writeBeginProcess( OTF_Writer* writer,
                                  uint64_t time,
                                  uint32_t process );


/**
 * Write a end process record
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param time      Time when process was referenced for the last time. 
 * @param process   Process identifier > 0.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
 
int OTF_Writer_writeEndProcess( OTF_Writer* writer,
                                uint64_t time,
                                uint32_t process );


/**
 * Write an file operation record
 *
 * @param writer    Initialized OTF_Writer instance.
 *
 * @param time      Time when process was referenced for the last time. 
 *
 * @param fileid    File identifier > 0.
 *
 * @param handleid  File open identifier.
 *
 * @param process   Process identifier > 0.
 *
 * @param operation Type of file operation @see OTF_Handler_FileOperation()
 *
 * @param bytes     Depends on operation @see OTF_Handler_FileOperation()
 * @param duration  time spent in the file operation
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeFileOperation( OTF_Writer* writer,
                                   uint64_t time,
                                   uint32_t fileid,
                                   uint32_t process,
                                   uint64_t handleid,
                                   uint32_t operation,
                                   uint64_t bytes,
                                   uint64_t duration,
                                   uint32_t source );

/* *** public snapshot record write handlers *** */

/**
 * Write a snapshot comment record.
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param time      Comments need a timestamp for a proper positioning in the 
 *                  trace.
 * @param process   Comments also need a process identifier for a proper 
 *                  positioning in the trace. 
 * @param comment   Arbitrary comment string.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
 
int OTF_Writer_writeSnapshotComment( OTF_Writer* writer, 
                                  uint64_t time, 
                                  uint32_t process, 
                                  const char* comment );


/** 
 * Write an enter snapshot which provides information about a past
 * function call
 *
 * @param writer        Initialized OTF_Writer instance.
 * @param time          Time when the snapshot was written(current time).
 * @param originaltime  Time when the according enter record was entered.
 *                      This call is still on the stack.(It has not been left
 *                      yet)
 * @param function      Function that the has been entered
 *                      OTF_Writer_defFunction.
 * @param process       Process where action took place.
 * @param source        Optional reference to source code.
 *
 * @return              1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeEnterSnapshot( OTF_Writer* writer, 
                           uint64_t time, 
                           uint64_t originaltime, 
                           uint32_t function, 
                           uint32_t process, 
                           uint32_t source );

/**
 * Write a send snapshot which provides information about a past
 * message send operation that is still pending, i.e. not yet received
 *
 * @param writer        Initialized OTF_Writer instance.
 * @param time          Time when the snapshot was written(current time).
 * @param originaltime  Time when the message was sent
 * @param sender        Sender of the message.
 * @param receiver      Receiver of the message.
 * @param procGroup     Optional process-group sender and receiver belong to,
 *                      '0' for no group.
 * @param tag           Optional message type information.
 * @param source        Optional reference to source code.
 *
 * @return              1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeSendSnapshot( OTF_Writer* writer,
                                  uint64_t time,
                                  uint64_t originaltime,
                                  uint32_t sender,
                                  uint32_t receiver,
                                  uint32_t procGroup,
                                  uint32_t tag,
                                  uint32_t source );


/**
 * Write a snapshot record for an open (and not yet closed) file
 *
 * @param writer        Initialized OTF_Writer instance.
 * @param time          Time when the snapshot was written(current time).
 * @param originaltime  Time when the message was sent.
 * @param fileid        File identifier.
 * @param process       Process where the file was opened.
 * @param handleid      Unique file open identifier. @see OTF_Handler_FileOperation()
 * @param source        Optional reference to source code.
 *
 * @return              1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeOpenFileSnapshot( OTF_Writer* writer,
                                      uint64_t time,
                                      uint64_t originaltime,
                                      uint32_t fileid,
                                      uint32_t process,
                                      uint64_t handleid,
                                      uint32_t source );


                           
/* *** public statistics record write handlers *** */


/**
 * Write a summary comment record.
 *
 * @param writer    Initialized OTF_Writer instance.
 * @param time      Comments need a timestamp for a proper positioning in the 
 *                  trace.
 * @param process   Comments also need a process identifier for a proper 
 *                  positioning in the trace. 
 * @param comment   Arbitrary comment string.
 *
 * @return          1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
 
int OTF_Writer_writeSummaryComment( OTF_Writer* writer, 
                                  uint64_t time, 
                                  uint32_t process, 
                                  const char* comment );


/**
 * Write a function summary record.
 *
 * @param writer       Initialized OTF_Writer instance.
 * @param time         Time when summary was computed. 
 * @param function     Function as defined with 
 *                     OTF_Handler_DefFunction.
 * @param process      Process of the given function.
 * @param count        Number of invocations.
 * @param excltime     Time spent exclusively in the given function.
 * @param incltime     Time spent in the given function including all
 *                     sub-routine calls.
 *
 * @return             1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */

int OTF_Writer_writeFunctionSummary( OTF_Writer* writer, 
        uint64_t time, uint32_t function, uint32_t process, 
        uint64_t count, uint64_t excltime, uint64_t incltime );

/**
 * Write a functiongroup summary record.
 *
 * @param writer         Initialized OTF_Writer instance.
 * @param time           Time when summary was computed. 
 * @param functiongroup  Function group as defined with 
 *                       OTF_Handler_DefFunctionGroup.
 * @param process        Process of the given function group.
 * @param count          Number of invocations.
 * @param excltime       Time spent exclusively in the given function group.
 * @param incltime       Time spent in the given function group including all
 *                       sub-routine calls.
 *
 * @return               1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */

int OTF_Writer_writeFunctionGroupSummary( OTF_Writer* writer, 
        uint64_t time,  uint32_t functiongroup,  uint32_t process,  
        uint64_t count,  uint64_t excltime,  uint64_t incltime );

/**
 * Write a message summary record.
 *
 * @param writer         Initialized OTF_Writer instance.
 * @param time           Time when summary was computed. 
 * @param process        Process where messages originated.
 * @param peer           Process where the message is sent to
 * @param comm           Communicator of message summary
 * @param tag            Message type/tag.
 * @param number_sent    The number of messages sent.
 * @param number_recved  The number of messages received.
 * @param bytes_sent     The number of bytes sent via messages of the given
 *                       type.
 * @param bytes_recved   The number of bytes received through messages of the 
 *                       given type.
 *
 * @return               1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */

int OTF_Writer_writeMessageSummary( OTF_Writer* writer, 
        uint64_t time, uint32_t process, uint32_t peer,
        uint32_t comm, uint32_t tag,  uint64_t number_sent,
        uint64_t number_recved, uint64_t bytes_sent, uint64_t bytes_recved );


/**
 * Writes a file operation summary record.
 *
 * @param writer         Initialized OTF_Writer instance.
 * @param time           Time when summary was computed.
 * @param fileid         File identifier or 0 for all  files.
 * @param process        Process where file operations occured.
 * @param nopen          Number of files opened.
 * @param nclose         Number of files closed.
 * @param nread          Number of read events.
 * @param nwrite         Number of write events.
 * @param nseek          Number of seek events.
 * @param bytesread      Number of bytes read.
 * @param byteswrite     Number of bytes written.
 *
 * @return               1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeFileOperationSummary( OTF_Writer* writer, uint64_t time,
        uint32_t fileid, uint32_t process, uint64_t nopen, uint64_t nclose,
        uint64_t nread, uint64_t nwrite, uint64_t nseek, uint64_t bytesread,
        uint64_t byteswrite );


/**
 * Writes a file group operation summary record.
 *
 * @param writer         Initialized OTF_Writer instance.
 * @param time           Time when summary was computed.
 * @param groupid        File group identifier or 0 for all  files/groups.
 * @param process        Process where file operations occured.
 * @param nopen          Number of files opened.
 * @param nclose         Number of files closed.
 * @param nread          Number of read events.
 * @param nwrite         Number of write events.
 * @param nseek          Number of seek events.
 * @param bytesread      Number of bytes read.
 * @param byteswrite     Number of bytes written.
 *
 * @return               1 on success, 0 if an error occurs.       
 *
 * \ingroup writer
 */
int OTF_Writer_writeFileGroupOperationSummary( OTF_Writer* writer, uint64_t time,
        uint32_t groupid, uint32_t process, uint64_t nopen, uint64_t nclose,
        uint64_t nread, uint64_t nwrite, uint64_t nseek, uint64_t bytesread,
        uint64_t byteswrite );
/* *** private member functions *** */


/** For a process with id 'processId' return a stream id of the stream the
    data is to be written to. If no mapping has been set so far it is defined
    in a way such that it is added to the stream with the least processes.
        \ingroup writer */
uint32_t OTF_Writer_mapProcess( OTF_Writer* writer, uint32_t processId );


/** Return the stream with the given stream id. If there is no such stream yet
    create one and append it to 'streams'. \ingroup writer */
OTF_WStream* OTF_Writer_getStream( OTF_Writer* writer, uint32_t stream );

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* OTF_WRITER_H */