1.2.1 (revision 3238)
Usage in writing mode

Usage in writing mode - a simple example

This is a short example of how to use the OTF2 writing interface.

First include the OTF2 header.

  #include <otf2/otf2.h>

For this example an additional include statement is necessary.

  #include <stdlib.h>

Furthermore this example uses a function delivering dummy timestamps. Real world applications will use a timer like gettimeofday.

  OTF2_TimeStamp get_time( void )
  {
      static uint64_t sequence;
      return sequence++;
  }

Define a pre and post flush callback. If no memory is left in OTF2's internal memory buffer or the writer handle is closed a memory buffer flushing routine is triggered. The pre flush callback is triggered right before a buffer flush. It needs to return either OTF2_FLUSH to flush the recorded data to a file or OTF2_NO_FLUSH to supress flushing data to a file. The post flush callback is triggered right after a memory buffer flush. It has to return a current timestamp which is recorded to mark the time spend in a buffer flush.

  OTF2_FlushType pre_flush( void*            userData,
                            OTF2_FileType    fileType,
                            OTF2_LocationRef location,
                            void*            callerData,
                            bool             final )
  {
      return OTF2_FLUSH;
  }

  OTF2_TimeStamp post_flush( void*            userData,
                             OTF2_FileType    fileType,
                             OTF2_LocationRef location )
  {
      return get_time();
  }

  OTF2_FlushCallbacks flush_callbacks =
  {
      .otf2_pre_flush  = pre_flush,
      .otf2_post_flush = post_flush
  };
  int main( int argc, char** argv )
  {

Create new archive handle.

      OTF2_Archive* archive = OTF2_Archive_Open( "ArchivePath", "ArchiveName", OTF2_FILEMODE_WRITE, 1024 * 1024, 4 * 1024 * 1024, OTF2_SUBSTRATE_POSIX, OTF2_COMPRESSION_NONE );

Set the flush callbacks.

      OTF2_Archive_SetFlushCallbacks( archive, &flush_callbacks, NULL );

Define archive as master.

Get a local event writer and a local definition writer for location 0. Additionally a global definition writer is needed.

      OTF2_EvtWriter*       evt_writer        = OTF2_Archive_GetEvtWriter( archive, 0 );
      OTF2_DefWriter*       def_writer        = OTF2_Archive_GetDefWriter( archive, 0 );
      OTF2_GlobalDefWriter* global_def_writer = OTF2_Archive_GetGlobalDefWriter( archive );

Write an enter and a leave record for region 23 to the local event writer.

      OTF2_EvtWriter_Enter( evt_writer, NULL, get_time(), 23 );
      OTF2_EvtWriter_Leave( evt_writer, NULL, get_time(), 23 );

Write definitions for the strings as the first records to the global definition writer.

      OTF2_GlobalDefWriter_WriteString( global_def_writer, 0, "" );
      OTF2_GlobalDefWriter_WriteString( global_def_writer, 1, "Master Process" );
      OTF2_GlobalDefWriter_WriteString( global_def_writer, 2, "Main Thread" );
      OTF2_GlobalDefWriter_WriteString( global_def_writer, 3, "MyFunction" );
      OTF2_GlobalDefWriter_WriteString( global_def_writer, 4, "Alternative function name (e.g. mangled one)" );
      OTF2_GlobalDefWriter_WriteString( global_def_writer, 5, "Computes something" );
      OTF2_GlobalDefWriter_WriteString( global_def_writer, 6, "MyHost" );
      OTF2_GlobalDefWriter_WriteString( global_def_writer, 7, "node" );

Write definition for the code region which was just entered and left to the global definition writer.

Write the system tree including a definition for the location group to the global definition writer.

Write a definition for the location to the global definition writer.

At the end, close the archive and exit. All opened event and definition writers are closed automatically and the according files are created.

      OTF2_Archive_Close( archive );

      return EXIT_SUCCESS;
  }

To compile your program use a command like:

  gcc `otf2-config --cflags` -c otf2_writer_example.c -o otf2_writer_example.o

Now you can link your program with:

  gcc otf2_writer_example.o `otf2-config --ldflags` `otf2-config --libs` -o otf2_writer_example