1.2 (revision 3183)

Usage in reading mode

Usage in reading mode - a simple example

This is a short example of how to use the OTF2 reading interface. It shows hows to define and register callbacks and how to use the reader interface to read all events of a given OTF2 archive.

First include the OTF2 header.

  #include <otf2/otf2.h>

For this example two additional include statements are necessary.

  #include <stdlib.h>
  #include <string.h>
  #include <stdint.h>
  #include <inttypes.h>

Define an event callback for entering and leaving a region.

  OTF2_CallbackCode
  Enter_print( OTF2_LocationRef    location,
               OTF2_TimeStamp      time,
               void*               userData,
               OTF2_AttributeList* attributes,
               OTF2_RegionRef      region )
  {
      printf( "Entering region %u at location: %" PRIu64 " at time %" PRIu64 ".\n",
              region, location, time );

      return OTF2_SUCCESS;
  }

  OTF2_CallbackCode
  Leave_print( OTF2_LocationRef    location,
               OTF2_TimeStamp      time,
               void*               userData,
               OTF2_AttributeList* attributes,
               OTF2_RegionRef      region )
  {
      printf( "Leaving region %u at location: %" PRIu64 " at time %" PRIu64 ".\n",
              region, location, time );

      return OTF2_SUCCESS;
  }

Define a definition callback that opens a new local event reader for each found location definition. The global event reader will use only events from opened local event readers. Therefore, if only a subset of locations should be read from, only for those locations a local event reader has to be opened. In addition, open a local definition reader, if there are local definitions present in the trace archive. Local definitions contain location specific definitions. Please note: Local definitions must be read in order to use automated identifierer translation. Otherwise, all delivered identifiers are invalid.

  OTF2_CallbackCode
  GlobDefLocation_Register( void*                 userData,
                            OTF2_LocationRef      location,
                            OTF2_StringRef        name,
                            OTF2_LocationType     locationType,
                            uint64_t              numberOfEvents,
                            OTF2_LocationGroupRef locationGroup )
  {
      OTF2_Reader* reader = ( OTF2_Reader* )userData;
      OTF2_EvtReader* evt_reader = OTF2_Reader_GetEvtReader( reader, location );

      OTF2_DefReader* def_reader = OTF2_Reader_GetDefReader( reader, location );
      uint64_t definitions_read = 0;
      OTF2_Reader_ReadAllLocalDefinitions( reader, def_reader, &definitions_read );
  }
  int main( int argc, char** argv )
  {

Create a new reader handle. The path to the OTF2 anchor file must be provided as argument.

      OTF2_Reader* reader = OTF2_Reader_Open( "ArchivePath/ArchiveName.otf2" );

Get a global definition reader with the above reader handle as argument.

      OTF2_GlobalDefReader* global_def_reader = OTF2_Reader_GetGlobalDefReader( reader );

Register the above defined global definition callbacks. All other definition callbacks will be deactivated.

      OTF2_GlobalDefReaderCallbacks* global_def_callbacks = OTF2_GlobalDefReaderCallbacks_New();
      OTF2_GlobalDefReaderCallbacks_SetLocationCallback( global_def_callbacks, &GlobDefLocation_Register );
      OTF2_Reader_RegisterGlobalDefCallbacks( reader, global_def_reader, global_def_callbacks, reader );
      OTF2_GlobalDefReaderCallbacks_Delete( global_def_callbacks );

Read all global definitions. Everytime a location definition is read, the previosly registered callback is triggered. In definitions_read the number of read definitions is returned.

      uint64_t definitions_read = 0;
      OTF2_Reader_ReadAllGlobalDefinitions( reader, global_def_reader, &definitions_read );

Open a new global event reader. This global reader automatically contains all previously opened local event readers.

      OTF2_GlobalEvtReader* global_evt_reader = OTF2_Reader_GetGlobalEvtReader( reader );

Register the above defined global event callbacks. All other global event callbacks will be deactivated.

      OTF2_GlobalEvtReaderCallbacks* event_callbacks = OTF2_GlobalEvtReaderCallbacks_New();
      OTF2_GlobalEvtReaderCallbacks_SetEnterCallback( event_callbacks, &Enter_print );
      OTF2_GlobalEvtReaderCallbacks_SetLeaveCallback( event_callbacks, &Leave_print );

      OTF2_Reader_RegisterGlobalEvtCallbacks( reader, global_evt_reader, event_callbacks, NULL );
      OTF2_GlobalEvtReaderCallbacks_Delete( event_callbacks );

Read all events in the OTF2 archive. The events are automatically ordered by the time they occured in the trace. Everytime an enter or leave event is read, the previously registered callbacks are triggered. In events_read the number of read events is returned.

      uint64_t events_read = 0;
      OTF2_Reader_ReadAllGlobalEvents( reader, global_evt_reader, &events_read );

At the end, close the reader and exit. All opened event and definition readers are closed automatically.

      OTF2_Reader_Close( reader );

      return EXIT_SUCCESS;
  }

To compile your program use a command like:

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

Now you can link your program with:

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