3.0-rc2 (revision 337012f1)
Data Structures | Typedefs
Operating OTF2 in a multi-threads context

Data Structures

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

Typedefs

typedef struct OTF2_LockObject * OTF2_Lock
 Opaque type for a locking object. More...
 
typedef OTF2_CallbackCode(* OTF2_Locking_Create) (void *userData, OTF2_Lock *lock)
 Creates a new locking object. More...
 
typedef OTF2_CallbackCode(* OTF2_Locking_Destroy) (void *userData, OTF2_Lock lock)
 Destroys a locking object. More...
 
typedef OTF2_CallbackCode(* OTF2_Locking_Lock) (void *userData, OTF2_Lock lock)
 Locks a locking object. More...
 
typedef OTF2_CallbackCode(* OTF2_Locking_Unlock) (void *userData, OTF2_Lock lock)
 Unlocks a locking object. More...
 
typedef void(* OTF2_Locking_Release) (void *userData)
 Signals the end of life of the OTF2_Archive or OTF2_Reader object to the locking callbacks. More...
 

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 operated 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 struct OTF2_LockObject* OTF2_Lock

Opaque type for a locking object.

A callback implementation should implement the struct OTF2_LockObject.

Since
Version 1.5
typedef OTF2_CallbackCode( * OTF2_Locking_Create) (void *userData, OTF2_Lock *lock)

Creates a new locking object.

Parameters
userDataValue from parameter userData passed to OTF2_Archive_SetLockingCallbacks or OTF2_Reader_SetLockingCallbacks respectively.
[out]lockReference 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 parameter 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 parameter 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 OTF2_CallbackCode( * OTF2_Locking_Unlock) (void *userData, OTF2_Lock lock)

Unlocks a locking object.

Parameters
userDataValue from parameter 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.
typedef void( * OTF2_Locking_Release) (void *userData)

Signals the end of life of the OTF2_Archive or OTF2_Reader object to the locking callbacks.

All locking objects created by the OTF2 object were already destroyed and no further calls to the callbacks will be done after this call.

This callback is optional.

Parameters
userDataValue from parameter userData passed to OTF2_Archive_SetLockingCallbacks or OTF2_Reader_SetLockingCallbacks respectively.
Since
Version 1.5
Returns
OTF2_CALLBACK_SUCCESS or OTF2_CALLBACK_ERROR.