Sun Studio 12：线程分析器用户指南

附录 A 线程分析器用户 API

线程分析器可以识别 OpenMP 指令、POSIX 线程和 Solaris 线程提供的大多数标准同步 API 和构造。但是，该工具无法识别用户定义的同步，而且在您使用这样的同步时可能报告假的数据争用。例如，该工具无法识别通过手动编码汇编语言代码实现的旋转锁定。

如果代码包括用户定义的同步，则将线程分析器支持的用户 API 插入到程序中以标识那些同步。此标识允许线程分析器识别同步并减少误报数。下面列出了用户 API：

A.1 线程分析器的用户 API

表 A–1 线程分析器用户 API


`tha_notify_acquire_lock(id)()`	在程序尝试获取用户定义的锁之前立即插入。
`tha_notify_lock_acquired(id)()`	在成功获取用户定义的锁之后立即插入。
`tha_notify_writelock_acquired(id)()`	在写入模式下成功获取用户定义的读写锁之后立即插入。
`tha_notify_readlock_acquired(id)()`	在读取模式下成功获取用户定义的读写锁之后立即插入。
`tha_notify_lock_released(id)()`	在成功释放用户定义的锁（包括读写锁）之后立即插入。
`tha_notify_sync_post_begin(id)()`	在执行用户定义的后同步之前立即插入。
`tha_notify_sync_post_end(id)()`	在执行用户定义的后同步之后立即插入。
`tha_notify_sync_wait_begin(id)()`	执行用户定义的等待同步之前立即插入。
`tha_notify_sync_wait_end(id)()`	执行用户定义的等待同步之后立即插入。

提供了 API 的 C/C++ 版本和 Fortran 版本。每个 API 调用都采用单个参数 id，其值应该唯一标识同步对象。

在 API 的 C/C++ 版本中，参数类型为 uintptr_t，在 32 位模式下其长度为 4 字节，在 64 位模式下其长度为 8 字节。调用任何 API 时，都需要将 #include <tha_interface.h> 添加到 C/C++ 源文件中。

在 API 的 Fortran 版本中，参数类型为整型 tha_sobj_kind，在 32 位和 64 位模式下其长度都为 8 字节。调用任何 API 时，都需要将 "tha_finterface.h" 添加到 Fortran 源文件中。要唯一标识同步对象，每个不同同步对象的参数 ID 应具有不同的值。一种执行此操作的方法是将同步对象的地址值用作 ID。以下代码示例说明如何使用 API 避免误报的数据争用：

# 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;

有关用户 API 的更多信息，请参见 libtha.3 手册页。

A.2 其他可识别的 API

以下几部分详细介绍线程分析器可识别的 API：

A.2.1 POSIX 线程 API

pthread_mutex_lock()

pthread_mutex_trylock()

pthread_mutex_unlock()

pthread_rwlock_rdlock()

pthread_rwlock_tryrdlock()

pthread_rwlock_wrlock()

pthread_rwlock_trywrlock()

pthread_rwlock_unlock()

pthread_create()

pthread_join()

pthread_cond_signal()

pthread_cond_broadcast()

pthread_cond_wait()

pthread_cond_timedwait()

pthread_cond_reltimedwait_np()

pthread_barrier_init()

pthread_barrier_wait()

pthread_spin_lock()

pthread_spin_unlock()

pthread_spin_trylock()

pthread_mutex_timedlock()

pthread_mutex_reltimedlock_np()

pthread_rwlock_timedrdlock()

pthread_rwlock_reltimedrdlock_np()

pthread_rwlock_timedwrlock()

pthread_rwlock_reltimedwrlock_np()

sem_post()

sem_wait()

sem_trywait()

sem_timedwait()

sem_reltimedwait_np()

A.2.2 Solaris 线程 API

mutex_lock()

mutex_trylock()

mutex_unlock()

rw_rdlock()

rw_tryrdlock()

rw_wrlock()

rw_trywrlock()

rw_unlock()

thr_create()

thr_join()

cond_signal()

cond_broadcast()

cond_wait()

cond_timedwait()

cond_reltimedwait()

sema_post()

sema_wait()

sema_trywait()

A.2.3 内存分配 API

calloc()

malloc()

realloc()

valloc()

memalign()

A.2.4 OpenMP API

有关更多信息，请参见《Sun Studio 12: OpenMP API User’s Guide》。