1.2 (revision 3183)
Data Structures | Typedefs

OTF2_Callbacks.h File Reference

This header file provides all user callbacks. More...

#include <stdio.h>
#include <stdbool.h>
#include <otf2/OTF2_ErrorCodes.h>
#include <otf2/OTF2_GeneralDefinitions.h>

Go to the source code of this file.

Data Structures

struct  OTF2_FileSionCallbacks
 Structure holding the SION callbacks. More...
struct  OTF2_FlushCallbacks
 Structure holding the flush callbacks. More...
struct  OTF2_MemoryCallbacks
 Structure holding the memory callbacks. More...

Typedefs

typedef int(* OTF2_FileSionClose )(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, int sid)
 Callbacks to wrap sion_parclose_mpi() for the OTF2 SION substrate.
typedef OTF2_ErrorCode(* OTF2_FileSionGetRank )(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, int32_t *rank)
 Provides location->rank translation, when using the SION substrate.
typedef int(* OTF2_FileSionOpen )(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, const char *fname, const char *fileMode, long long int *chunkSize, int *fsblkSize, FILE **filePtr)
 Callbacks to wrap sion_paropen_mpi() for the OTF2 SION substrate. Every paramater that can be given by OTF2 is named equally like the the according paramater of sion_paropen_mpi(). Therfore, these given parameters MUST be given to SION.
typedef void *(* OTF2_MemoryAllocate )(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, void **perBufferData, uint64_t chunkSize)
 Function pointer for allocating memory for chunks.
typedef void(* OTF2_MemoryFreeAll )(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, void **perBufferData, bool final)
 Function pointer to release all allocated chunks.
typedef OTF2_TimeStamp(* OTF2_PostFlushCallback )(void *userData, OTF2_FileType fileType, OTF2_LocationRef location)
 Definition for the post flush callback.
typedef OTF2_FlushType(* OTF2_PreFlushCallback )(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, void *callerData, bool final)
 Definition for the pre flush callback.

Detailed Description

This header file provides all user callbacks.

Maintainer:
Michael Wagner <michael.wagner@zih.tu-dresden.de>
Authors:
Dominic Eschweiler <d.eschweiler@fz-juelich.de>, Michael Wagner <michael.wagner@zih.tu-dresden.de>

Typedef Documentation

typedef int( * OTF2_FileSionClose)(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, int sid)

Callbacks to wrap sion_parclose_mpi() for the OTF2 SION substrate.

Parameters:
userDataData passed to the call OTF2_Archive_SetFileSionCallbacks.
fileTypeThe file type for which the file close is called.
locationThe location ID of the writer for which the flush has happened (for file types without an ID this is OTF2_UNDEFINED_LOCATION).
sidSion file handle.
Returns:
Return value of sion_parclose_mpi()
typedef OTF2_ErrorCode( * OTF2_FileSionGetRank)(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, int32_t *rank)

Provides location->rank translation, when using the SION substrate.

In case no OTF2_FileSionOpen and no OTF2_FileSionClose callback is given, the SION substrate still needs information what rank the current location has.

Parameters:
userDataData passed to the call OTF2_Archive_SetFileSionCallbacks.
fileTypeThe file type for which the file close is called.
locationThe location ID of the writer for which the flush has happened (for file types without an ID this is OTF2_UNDEFINED_LOCATION).
[out]rankThe associated MPI rank for the location.
Returns:
OTF2_SUCCESS, or error code.
typedef int( * OTF2_FileSionOpen)(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, const char *fname, const char *fileMode, long long int *chunkSize, int *fsblkSize, FILE **filePtr)

Callbacks to wrap sion_paropen_mpi() for the OTF2 SION substrate. Every paramater that can be given by OTF2 is named equally like the the according paramater of sion_paropen_mpi(). Therfore, these given parameters MUST be given to SION.

Parameters:
userDataData passed to the call OTF2_Archive_SetFileSionCallbacks.
fileTypeThe file type for which the file open is called.
locationThe location ID of the writer for which the flush has happened (for file types without an ID this is OTF2_UNDEFINED_LOCATION).
fnameName of file, should equal on all tasks.
fileModeLike the type parameter of fopen.
[in,out]chunkSizeRequested space for this task.
[in,out]fsblkSizeBlocksize of filesystem, must be equal on all processors.
[out]filePtrFilepointer for this task.
Returns:
sion file handle integer (0, ...) -1 if error occured
typedef void*( * OTF2_MemoryAllocate)(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, void **perBufferData, uint64_t chunkSize)

Function pointer for allocating memory for chunks.

Please note: Do not use this feature if you do not really understand it. The OTF2 library is not able to do any kind of checks to validate if your memory management works properly. If you do not use it correctly OTF2's behaviour is undefined including dead locks and all that nasty stuff.

This function must return a pointer to a valid allocated memory location (just like malloc). This memory location must be of exact same size as the parameter 'chunkSize' provided with OTF2_Archive_Open().

Parameters:
userDataData passed to the call OTF2_Archive_SetMemoryCallbacks.
fileTypeThe file type for which the chunk is requested.
locationThe location ID of the writer for which the flush has happened (for file types without an ID this is OTF2_UNDEFINED_LOCATION).
perBufferDataA writeable pointer to store callee data. For the first call this will be NULL.
chunkSizeThe size of the requested chunk.
Returns:
Returns a the allocated memory on success, NULL if an error occurs.
typedef void( * OTF2_MemoryFreeAll)(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, void **perBufferData, bool final)

Function pointer to release all allocated chunks.

Please note: Do not use this feature if you do not really understand it. The OTF2 library is not able to do any kind of checks to validate if your memory management works properly. If you do not use it correctly OTF2's behaviour is undefined including dead locks and all that nasty stuff.

This function must free all those memory locations that were allocated for a buffer handle with the according allocate function. Please note: This is different from a posix free(). You must free _all_ memory locations for that were allocated for exactly this buffer handle.

Parameters:
userDataData passed to the call OTF2_Archive_SetMemoryCallbacks.
fileTypeThe file type for which free is requested.
locationThe location ID of the writer for which the flush has happened (for file types without an ID this is OTF2_UNDEFINED_LOCATION).
perBufferDataA writeable pointer to store callee data. For the first call this will be NULL.
finalIndicates whether this is the final free when closing the writer objects. perBufferData should be handled than.
typedef OTF2_TimeStamp( * OTF2_PostFlushCallback)(void *userData, OTF2_FileType fileType, OTF2_LocationRef location)

Definition for the post flush callback.

This callback is triggered right after flushing the recorded data into file when running out of memory. The main function of this callback is to provide a timestamp for the end of flushing data into a file. So an according record can be written correctly.

Parameters:
userDataData passed to the call OTF2_Archive_SetFlushCallbacks.
fileTypeThe file type for which the flush has happened.
locationThe location ID of the writer for which the flush has happened (for file types without an ID this is OTF2_UNDEFINED_LOCATION).
Returns:
Returns a timestamp for the end of flushing data into a file.
typedef OTF2_FlushType( * OTF2_PreFlushCallback)(void *userData, OTF2_FileType fileType, OTF2_LocationRef location, void *callerData, bool final)

Definition for the pre flush callback.

This callback is triggered right before flushing the recorded data into file when running out of memory.

Parameters:
userDataData passed to the call OTF2_Archive_SetFlushCallbacks.
fileTypeThe type of file for what this buffer holds data.
locationThe location id for what this buffer holds data. This is only valid for files of type OTF2_FILETYPE_LOCAL_DEFS or OTF2_FILETYPE_EVENTS. For other files this is OTF2_UNDEFINED_LOCATION. A special case exists for files of type OTF2_FILETYPE_EVENTS in writing mode. The location ID may still be OTF2_UNDEFINED_LOCATION. In this case if the application wants to write the data from the buffer into the file, the application needs to provide a valid location ID via a call to OTF2_EvtWriter_SetLocationID() and utilizing the callerData argument.
callerDataDepending of the fileType, this can be an OTF2_EvtWriter, OTF2_GlobalDefWriter, OTF2_DefWriter.
finalIndicates whether this is the final flush when closing the writer objects.
Returns:
Returns OTF2_FLUSH or OTF2_NO_FLUSH.