1.5.1 (revision 4026)
Data Structures | Typedefs
Operating OTF2 in a multi-threads context
OTF2 callbacks

Data Structures

struct  OTF2_LockingCallbacks
 Struct which holds all collective callbacks. More...

Typedefs

typedef OTF2_CallbackCode(* OTF2_Locking_Create )(void *userData, OTF2_Lock *lock)
 Creates a new locking object.
typedef OTF2_CallbackCode(* OTF2_Locking_Destroy )(void *userData, OTF2_Lock lock)
 Destroys a locking object.
typedef OTF2_CallbackCode(* OTF2_Locking_Lock )(void *userData, OTF2_Lock lock)
 Locks a locking object.
typedef void(* OTF2_Locking_Release )(void *userData)
 Optionally called in OTF2_Archive_Close or OTF2_Reader_Close respectively.
typedef OTF2_CallbackCode(* OTF2_Locking_Unlock )(void *userData, OTF2_Lock lock)
 Unlocks a locking object.

Detailed Description

The OTF2 objects OTF2_Archive and OTF2_Reader including all derived objects from these are by default not thread safe. That means it is undefined behavior to operate any of these objects concurrently by multiple threads. Note that two independent OTF2_Archive or OTF2_Reader objects and there derived objects can be operatated by multiple threads concurrently though.

It is necessary to register the following locking callbacks to make a OTF2_Archive and OTF2_Reader and their derived objects thread safe. The created locking objects should have normal locking semantics, no recursive or nesting capability is needed.

OTF2 provides two locking callbacks implementations for Pthread and OpenMP. See the header files otf2/OTF2_Pthread_Locks.h and otf2/OTF2_OpenMP_Locks.h. For a usage of these headers have a look into the installed usage examples otf2_pthread_writer_example.c and otf2_openmp_writer_example.c.

If any locking callback returns !OTF2_CALLBACK_SUCCESS, than OTF2 returns to the caller the error OTF2_ERROR_LOCKING_CALLBACK.


Typedef Documentation

typedef OTF2_CallbackCode( * OTF2_Locking_Create)(void *userData, OTF2_Lock *lock)

Creates a new locking object.

Parameters:
userDataValue from paramter userData passed to OTF2_Archive_SetLockingCallbacks or OTF2_Reader_SetLockingCallbacks respectively.
lock[out]Reference to pointer to new lock object.
Since:
Version 1.5
Returns:
OTF2_CALLBACK_SUCCESS or OTF2_CALLBACK_ERROR.
typedef OTF2_CallbackCode( * OTF2_Locking_Destroy)(void *userData, OTF2_Lock lock)

Destroys a locking object.

Parameters:
userDataValue from paramter userData passed to OTF2_Archive_SetLockingCallbacks or OTF2_Reader_SetLockingCallbacks respectively.
lockLock object to destroy.
Since:
Version 1.5
Returns:
OTF2_CALLBACK_SUCCESS or OTF2_CALLBACK_ERROR.
typedef OTF2_CallbackCode( * OTF2_Locking_Lock)(void *userData, OTF2_Lock lock)

Locks a locking object.

Parameters:
userDataValue from paramter userData passed to OTF2_Archive_SetLockingCallbacks or OTF2_Reader_SetLockingCallbacks respectively.
lockLock object to lock.
Since:
Version 1.5
Returns:
OTF2_CALLBACK_SUCCESS or OTF2_CALLBACK_ERROR.
typedef void( * OTF2_Locking_Release)(void *userData)

Optionally called in OTF2_Archive_Close or OTF2_Reader_Close respectively.

Since:
Version 1.5
Returns:
OTF2_CALLBACK_SUCCESS or OTF2_CALLBACK_ERROR.
typedef OTF2_CallbackCode( * OTF2_Locking_Unlock)(void *userData, OTF2_Lock lock)

Unlocks a locking object.

Parameters:
userDataValue from paramter userData passed to OTF2_Archive_SetLockingCallbacks or OTF2_Reader_SetLockingCallbacks respectively.
lockLock object to unlock.
Since:
Version 1.5
Returns:
OTF2_CALLBACK_SUCCESS or OTF2_CALLBACK_ERROR.