マニュアルページ libtha.3




名前

     libtha - Sun Studio スレッドアナライザ (THA) と連携して使 用
     可能な API



形式 -- C/C++ 版 API

     cc   [   flag...   ]   file...   -ltha    -Linstall_path/lib
     -Rinstall_path/lib

     CC [ flag... ] file... -ltha

     #include "tha_interface.h"

     void tha_notify_acquire_lock (uintptr_t id);

     void tha_notify_lock_acquired (uintptr_t id);

     void tha_notify_writelock_acquired (uintptr_t id);

     void tha_notify_readlock_acquired (uintptr_t id);

     void tha_notify_release_lock (uintptr_t id);

     void tha_notify_lock_released (uintptr_t id);

     void tha_notify_sync_post_begin (uintptr_t id);

     void tha_notify_sync_post_end (uintptr_t id);

     void tha_notify_sync_wait_begin (uintptr_t id);

     void tha_notify_sync_wait_end (uintptr_t id);



形式 -- Fortran 版 API

     f95 [ flag... ] file... -ltha

     include "tha_finterface.h"

     subroutine tha_notify_acquire_lock (id)
     integer(kind=tha_sobj_kind) :: id

     subroutine tha_notify_lock_acquired (id)
     integer(kind=tha_sobj_kind) :: id

     subroutine tha_notify_writelock_acquired (id)
     integer(kind=tha_sobj_kind) :: id

     subroutine tha_notify_readlock_acquired (id)
     integer(kind=tha_sobj_kind) :: id


     subroutine tha_notify_release_lock (id)
     integer(kind=tha_sobj_kind) :: id

     subroutine tha_notify_lock_released (id)
     integer(kind=tha_sobj_kind) :: id

     subroutine tha_notify_sync_post_begin (id)
     integer(kind=tha_sobj_kind) :: id

     subroutine tha_notify_sync_post_end (id)
     integer(kind=tha_sobj_kind) :: id

     subroutine tha_notify_sync_wait_begin (id)
     integer(kind=tha_sobj_kind) :: id

     subroutine tha_notify_sync_wait_end (id)
     integer(kind=tha_sobj_kind) :: id



説明

     共有オブジェクト libtha.so は、Sun Studio スレッドアナライザ
     と連携して使用することができる API を提供します。

     スレッドアナライザは、OpenMP、POSIX スレッド、および Solaris
     ス レッドの提供する API と構文のうちもっとも標準的なものを認
     識することができます。ただし、このツールはユーザーが作成した
     同期化機構を認識することはできず、そうした同期化機構が使用さ
     れている場合に誤ってデータ競合を報告することがあります。たと
     えば、このツールは手動コーディングされたアセンブリを使用して
     実装されたスピンロックを認識できません。

     プログラムにユーザーが作成した同期化機構が含まれている 場 合
     は、 プ ロ グラムに libtha.so API への呼び出しを挿入すること
     で、それらの同期化機構をスレッドアナライザに通知することがで
     きます。これにより、ツールは同期化を認識し、誤って報告される
     データ競合数を減らすことができます。

     libtha.so API は、次のルーチンから構成されます。

     tha_notify_acquire_lock(): このルーチンは、プログラムが ユー
     ザー 定 義ロックを取得しようとする直前に呼び出すことができま
     す。

     tha_notify_lock_acquired(): このルーチンは、ユーザー定 義 の
     ロックが正常に取得された直後に呼び出すことができます。

     tha_notify_writelock_acquired(): このルーチンは、ユーザー 定
     義 の読み取り/書き込みロックが書き込みモードで正常に取得され
     た直後に呼び出すことができます。

     tha_notify_readlock_acquired(): このルーチンは、ユーザー定義
     の 読み取り/書き込みロックが読み取りモードで正常に取得された
     直後に呼び出すことができます。

     tha_notify_release_lock(): このルーチンは、ユーザー 定 義 の
     ロッ ク (読み取り/書き込みロックを含む) が解除される直前に呼
     び出すことができます。

     tha_notify_lock_released(): このルーチンは、ユーザー定 義 の
     ロッ ク (読み取り/書き込みロックを含む) が正常に解除された直
     後に呼び出すことができます。

     tha_notify_sync_post_begin(): このルーチンは、ユーザー定義の
     同期後の処理を実行する直前に呼び出すことができます。

     tha_notify_sync_post_end(): このルーチンは、ユーザー定義の同
     期後の処理を実行した直後に呼び出すことができます。

     tha_notify_sync_wait_begin(): このルーチンは、ユーザー定義の
     同期待ち処理を実行する直前に呼び出すことができます。

     tha_notify_sync_wait_end(): このルーチンは、ユーザー定義の同
     期待ち処理を実行した直後に呼び出すことができます。

     C/C++ 版の libtha API では、各関数は 1 つの引数 id を取 り、
     こ の  ID 値で、同期化オブジェクトを一意に識別するようにしま
     す。この引数の型は uintptr_t であり、<sys/types.h> に定義 さ
     れ て い ます。また、サイズは 32 ビットモードで 4 バイト、64
     ビットモードで 8 バイトです。

     Fortran 版の libtha API では、各サブルーチンは 1 つの引数 id
     を取り、この ID 値で、同期化オブジェクトを一意に識別するよう
     にします。この引数の型は整数で、サイズ は、 tha_finterface.h
     に 定 義されている tha_sobj_kind で指示され、32 ビットおよび
     64 ビットのどちらのモードでも 8 バイトです。

     同期化オブジェクトを一意に識別するため、引数 id は必ず同期化
     オ ブ ジェクトごとに異なる値を持つようにします。これを行う 1
     つの方法は、id 値を同期化オブジェクトのアドレスにすること で
     す。 このアドレスは、C/C++ では & 演算子、Fortran では loc()
     ライブラリルーチンを使用して取得できます。後述の「使用例」セ
     クションの例 1 を参照してください。

     libtha.so は、API ルーチンに「フック」(または疑似) エント リ
     ポイントのみ提供します。こうして、これらのルーチンを呼び出し
     て libtha.so とリンクされたプログラムは、スレッドアナライ ザ
     実験の制御下ばかりでなく、そうした実験の制御外でも実行するこ
     とができます。

     プログラムがスレッドアナライザ実験の制御下 (たとえ ば、 col-
     lect -r on の制御下) で実行されると、これら API ルーチンが働
     いて、スレッドアナライザに、プログラム内の同期化機構の情報が
     通知されます。

     プログラムがスレッドアナライザ実験の制御外 (たとえ ば、 col-
     lect  -r on の制御外) で実行された場合、API ルーチンは何の働
     きもしません。

     スレッドアナライザ実験の実行の詳細は、collect(1) を参照し て
     ください。



使用例

     例 1:

     次に示す例は Fotran での使用例で、 tha_notify_acquire_lock()
     お よ び  tha_notify_release_lock() を使用して、それぞれユー
     ザー定義ロックが取得または解除されたことをスレッドアナライザ
     に通知する方法を示しています。この例では、ロックオブジェクト
     のアドレスを id として使用して、一意にオブジェクトを識別して
     います。

          include "tha_finterface.h"

          integer :: my_lock
          integer(kind= tha_sobj_kind) :: id

          id = loc (my_lock)
          tha_notify_acquire_lock (id)
          call my_lock_routine(my_lock)
          tha_notify_lock_acquired (id)
          ...
          call my_unlock_routine(my_lock)
          tha_notify_lock_released (id)

     例 2:

     次に示す例は C/C++ での例で、tha_notify_sync_wait_begin() お
     よび tha_notify_sync_wait_end() を使用して、それぞれユーザー
     定義の待ち同期化の開始と終了をスレッドアナライザに通知する方
     法を示しています。

     また、この例は、それぞれ同期後の処理の直前と直後 に お け る
     tha_notify_sync_post_begin()          お        よ        び
     tha_notify_sync_post_end() の使用方法を示しています。

          #include "tha_interface.h"

          int busy_wait = 1;

          /* Code executed by thread 1 */
          tha_notify_sync_wait_begin(&busy_wait);
          while (busy_wait) {
             no_op();
          }
          tha_notify_sync_wait_end(&busy_wait);
          /* Code executed by thread 2 */
          tha_notify_sync_post_begin(&busy_wait);
          busy_wait =  0;
          tha_notify_sync_post_end(&busy_wait);



注意事項

     形式で示しているように、cc を使用して libtha とリンクさせ る
     方法としては、コマンド行で

          -Rinstall-path/lib -Linstall-path/lib -ltha

     を指定することをお勧めします。install-path は、コンパイラ が
     インストールされている場所 (デフォルトでは /opt/SUNWspro) で
     す。



属性

          _________________________________________________________
         | 属性の型         |           属性値                     |
         |__________________|______________________________________|
         | Stability Level  | Evolving                             |
         |__________________|______________________________________|


関連項目

     tha(1)analyzer(1)collect(1)collector(1)er_print(1)attributes(5)、および