APIs Recognized by Thread Analyzer

Language:

Thread Analyzer can recognize most standard synchronization APIs and constructs provided by OpenMP, POSIX threads, and Oracle Solaris threads. However, the tool cannot recognize user-defined synchronizations, and might report false positive data races if you employ such synchronizations. For example, the tool cannot recognize spin locking that is implemented through hand-coded assembly-language code.

Thread Analyzer User APIs

If your code includes user-defined synchronizations, insert user APIs supported by Thread Analyzer into the program to identify those synchronizations. This identification enables Thread Analyzer to recognize the synchronizations and reduce the number of false positives. Thread Analyzer user APIs are defined in libtha.so and are listed below.

Table 1 Thread Analyzer User APIs

Routine Name	Description
`tha_notify_acquire_lock()`	This routine can be called immediately before the program tries to acquire a user-defined lock.
`tha_notify_lock_acquired()`	This routine can be called immediately after a user-defined lock is successfully acquired.
`tha_notify_acquire_writelock()`	This routine can be called immediately before the program tries to acquire a user-defined read/write lock in write mode.
`tha_notify_writelock_acquired()`	This routine can be called immediately after a user-defined read/write lock is successfully acquired in write mode.
`tha_notify_acquire_readlock()`	This routine can be called immediately before the program tries to acquire a user-defined read/write lock in read mode.
`tha_notify_readlock_acquired()`	This routine can be called immediately after a user-defined read/write lock is successfully acquired in read mode.
`tha_notify_release_lock()`	This routine can be called immediately before a user-defined lock or read/write lock is to be released.
`tha_notify_lock_released()`	This routine can be called immediately after a user-defined lock or read/write lock is successfully released.
`tha_notify_sync_post_begin()`	This routine can be called immediately before a user-defined post synchronization is performed.
`tha_notify_sync_post_end()`	This routine can be called immediately after a user-defined post synchronization is performed.
`tha_notify_sync_wait_begin()`	This routine can be called immediately before a user-defined wait synchronization is performed.
`tha_notify_sync_wait_end()`	This routine can be called immediately after a user-defined wait synchronization is performed.
`tha_check_datarace_mem()`	This routine instructs Thread Analyzer to monitor or ignore accesses to a specified block of memory when doing data race detection.
`tha_check_datarace_thr()`	This routine instructs Thread Analyzer to monitor or ignore memory accesses by one or more threads when doing data race detection.

A C/C++ version and a Fortran version of the APIs are provided. Each API call takes a single argument id, whose value should uniquely identify the synchronization object.

In the C/C++ version of the APIs, the type of the argument is uintptr_t, which is 4 bytes long in 32-bit mode and 8 bytes long in 64-bit mode. You need to add #include <tha_interface.h> to your C/C++ source file when calling any of the APIs.

In the Fortran version of the APIs, the type of the argument is integer of kind tha_sobj_kind which is 8-bytes long in both 32-bit and 64–bit mode. You need to add #include "tha_finterface.h" to your Fortran source file when calling any of the APIs.

To uniquely identify a synchronization object, the argument id should have a different value for each different synchronization object. One way to do this is to use the value of the address of the synchronization object as the id. The following code example shows how to use the API to avoid a false positive data race.

Example 1 Example Using Thread Analyzer APIs to Avoid False Positive Data Races

# include <tha_interface.h>
...
/* Initially, the ready_flag value is zero */
...
/* Thread 1: Producer */
100   data = ...
101   pthread_mutex_lock (&mutex);
      tha_notify_sync_post_begin ((uintptr_t) &ready_flag);
102   ready_flag = 1;
      tha_notify_sync_post_end ((uintptr_t) &ready_flag);

103   pthread_cond_signal (&cond);
104   pthread_mutex_unlock (&mutex);
 
 
/* Thread 2: Consumer */
200   pthread_mutex_lock (&mutex);
      tha_notify_sync_wait_begin ((uintptr_t) &ready_flag);
201   while (!ready_flag) {
202       pthread_cond_wait (&cond, &mutex);   
203   }
      tha_notify_sync_wait_end ((uintptr_t) &ready_flag);
204   pthread_mutex_unlock (&mutex);
205   ... = data;

For more information on the user APIs, see the libtha(3) man page.