*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> ThreadForeach (5)              



NAME    [Toc]    [Back]

       Thread,  ThreadExcludeObj,  ThreadExcludeProc,  ThreadCreationObj,
    ThreadCreationProc,     ThreadTerminationObj,
       ThreadTerminationProc,    ThreadGetId,   ThreadIsInternal,
       ThreadTableInit,    ThreadTableLock,    ThreadTableUnlock,
       ThreadTableFree, ThreadLookup, ThreadUnlock, ThreadRemove,
       ThreadForeach, ThreadMutexPoll, ThreadMutexLock, ThreadMutexUnlock,
  ThreadAddr,  ThreadLockedAdd  -  Atom services
       used to develop Thread-safe analysis routines

SYNOPSIS    [Toc]    [Back]

       The following interfaces  are  defined  for  use  by  Atom
       instrumentation routines: #include <cmplrs/atom.inst.h>

       int ThreadExcludeObj(
               Obj *object,
               unsigned long i_flags ); int ThreadExcludeProc(
               Obj *object,
               Proc *procedure,
               unsigned  long  i_flags  ); extern Obj *ThreadCreationObj(

               void ); extern Proc *ThreadCreationProc(
               void ); extern Obj *ThreadTerminationObj(
               void ); extern Proc *ThreadTerminationProc(
               void );

       The following instrumentation routines are  retained  only
       for compatibility: int ThreadExitCall(
               Obj *object,
               unsigned long i_flags,
               const  char  *exit_routine_name ); int ThreadForkCall(

               Obj *object,
               unsigned long i_flags,
               const char *pre_fork_routine_name,
               const char *post_fork_routine_name );

       The following interfaces are defined for use by Atom analysis
 routines: #include <cmplrs/atom.anal.h>

       ThreadId ThreadGetId(
               void ); int ThreadIsInternal(
               ThreadId id ); ThreadTable *ThreadTableInit(
               unsigned long size_hint,
               unsigned    long    info_size    );   ThreadStatus
               ThreadTable *table,
               ThreadId id ); void ThreadTableUnlock(
               ThreadTable *table,
               ThreadId id ); void ThreadTableFree(
               ThreadTable *table ); void *ThreadLookup(
               ThreadTable *table,
               ThreadId id,
               unsigned long a_flags  );  ThreadStatus  ThreadUnlock(

               ThreadTable *table,
               ThreadId id ); ThreadStatus ThreadRemove(
               ThreadTable *table,
               ThreadId id ); ThreadStatus ThreadForeach(
               ThreadTable *table,
               ThreadId id,
               unsigned long a_flags,
               void *data,
               void *result,
               void  (*proc)(ThreadId,void  *,void  *,void  *) );
       void ThreadMutexPoll(
               int microseconds ); ThreadStatus ThreadMutexLock(
               ThreadMutex *mutex,
               ThreadId id ); void ThreadMutexUnlock(
               ThreadMutex *mutex ); ThreadMutex *ThreadAddr(
               ThreadTable *table,
               ThreadId id ); unsigned long ThreadLockedAdd(
               unsigned long *counter,
               unsigned long increment );

PARAMETERS    [Toc]    [Back]

       An instrumentation time object file that  has  been  built
       but  not yet written.  Options to control the instrumentation-time
 services. The same value may be  passed  to  all
       such  routines  that use it. The value is a bitwise-OR (|)
       of the following:

              THREAD_PTHREAD = application calls pthread_* routines
              THREAD_FORK        = application may fork
              THREAD_FLOAT      = analysis routines use floating-point
              An instrumentation  time  procedure  pointer.   The
              name  of  an  analysis routine that is to be called
              just before a thread terminates.  The  name  of  an
              analysis routine that is to be called just before a
              fork(2) or vfork(2) system call.  The  name  of  an
              analysis  routine that is to be called just after a
              fork(2) or vfork(2) system call; it will be  called
              in  both  the  parent  and the child process.  Suggested
 number of threads that the thread table typically
  needs  to  accommodate.  Number of bytes of
              data that the thread table needs  to  allocate  per
              thread.  Pointer to a thread table previously allocated
 by calling ThreadTableInit().  Unique identification
  number  for  a  thread,  as  provided  by
              ThreadGetId().    If   a_flags   has   the    value
              THREAD_LOCK,  a mutex will be claimed, to serialize
              access to the data for the current thread;  ThreadUnlock
  must  be  called to release the mutex after
              use.  A pointer to any data that the tool needs  to
              pass  to  the iteration callback function "proc" in
              its third argument.  A pointer to any data that the
              tool  needs to get back from the iteration callback
              function "proc" via its fourth argument.  Procedure
              to  be  called for each thread that has data in the
              specified thread table. It should  return  non-zero
              if  the  iteration  must stop, zero if it must continue.
  A mutual-exclusion lock, which contains the
              value  ThreadNoId  if  no thread holds the lock, or
              which contains the  identification  number  of  the
              thread  that does hold it.  Any unsigned long variable.
  Any unsigned long value.

DESCRIPTION    [Toc]    [Back]

       Atom's Thread* routines help you write thread-safe  analysis
 routines, for applications that use pthread_create and
       other POSIX thread services. See FILES below for a working
       example of a tool that uses these APIs.

   Instrumentation Services    [Toc]    [Back]
       The  ThreadExcludeObj  routine returns a non-zero value if
       the procedures of the specified object can not  be  safely
       instrumented with calls to analysis routines. If ThreadExcludeObj
 returns a non-zero value,  the  specified  object
       may only be instrumented via ThreadExitCall or ThreadForkCall.

       The ThreadExcludeProc routine returns a non-zero value  if
       the specified procedure can not be safely instrumented, in
       much the same way  that  ThreadExcludeObj  excludes  whole
       objects.   This routine acts as a more fine-grained filter
       for procedures in shared-libraries, and it takes over from
       ThreadExcludeObj  programs  that  were linked with archive

       The ThreadCreationProc routine returns a pointer to a procedure
 that can be instrumented with AddCallProc's ProcBefore
 option, to call an analysis routine whenever a thread
       is  created.  The  returned  Proc* can be used only if the
       procedure is defined in an object that has been  built  by
       BuildObj(5);  otherwise  the  returned  Proc* is NULL. The
       ThreadCreationObj routine returns a pointer to the  object
       that  needs  to be built. This helps a tool build only the
       objects it really needs to build.  The ThreadTerminateProc
       and  ThreadTerminateObj routines are similar but for calling
 an analysis routine when a thread terminates.

   Run-Time Analysis Services    [Toc]    [Back]
       The analysis  routines  of  an  Atom  tool  can  not  call
       pthread_*   routines,   because   only  one  copy  of  the
       libpthread library can be in control of a process. So, the
       Thread*  routines  provided  by  Atom's  analysis-services
       library provide  routines  that  support  mutexes  without
       using libpthread. Services for analyzing threads individually
 (for example, per-thread profiles) are also  provided
       by this Atom library.

       The  ThreadGetId routine returns the unique identification
       number for the thread that is  executing  this  code.  The
       value  ThreadNoId is returned if the current thread is one
       of the internal threads of the pthread library.

       The ThreadIsInternal routine returns a non-zero  value  if
       the  given thread id is that of a thread-management thread
       created within DECthreads. Such threads  are  usually  not

       The  ThreadTableInit  routine  allocates and initializes a
       table that records info_size bytes of per-thread  data  on
       any  number  of threads. A pointer to the data for a given
       thread is returned by calling ThreadLookup with the id  of
       the  thread.  The  first time ThreadLookup is called for a
       thread, its data is allocated and set to zero, unless  the
       THREAD_EXISTING  flags value is specified to prevent allocation
 for that call.  ThreadLookup  may  become  progressively
  less  efficient  as the number of threads known to
       the table exceeds the size_hint specified when  the  table
       was allocated with ThreadTableInit.

       ThreadLookup claims a mutex if the THREAD_LOCK flags value
       is specified; this is necessary when  Atom  analysis  routines
  are  profiling threads individually, but not if the
       table is being used in a non-threaded program (such as one
       that  monitors  threaded  programs  with  the  /proc  file
       system).  ThreadUnlock must be called to release the mutex
       after  the  thread  has  finished modifying its per-thread
       data. Note that the table may use one mutex  to  serialize
       access  to  more than one thread; optimally, each thread's
       data will have its own mutex, but this  cannot  be  relied

       The ThreadRemove routine breaks the connection between the
       thread id and its data in the thread  table,  for  example
       when  a  thread terminates.  THREAD_NO_DATA is returned if
       no data was found for the specified thread. If other  code
       uses  the THREAD_LOCK flags value to lock the table's perthread
 data, then  ThreadRemove  must  be  called  between
       calls  to  ThreadLookup  (with  THREAD_LOCK specified) and

       The ThreadForeach routine calls  the  specified  procedure
       for  every  thread  known  to  the table, in no particular
       order. The callback procedure must return zero to continue
       the iteration, or non-zero to stop it.

       The ThreadTableLock routine locks every current and future
       thread associated with the table, or it locks none if  any
       was already locked by the calling thread. The ThreadTableUnlock
 routine unlocks every thread known  to  the  table,
       except  for threads that are locked by the calling thread.
       These routines can be used to safeguard  mutexes  when  an
       instrumented application calls fork().

       The ThreadTableFree routine deallocates the memory used by
       the table. You must ensure that  no  thread  is  currently
       using the table or will use it.

       The  ThreadMutexPoll  routine  sets  the  period for which
       ThreadMutexLock  and  ThreadLookup  will  sleep,   between
       attempts  to  claim  a  mutex.  Periods  of zero to 999999
       microseconds are supported. If a negative period is specified
  (and by default), ThreadMutexLock adopts a repeating
       and varying schedule of intervals from 1 to 512K microseconds.

       The  ThreadMutexLock  routine  claims  the specified mutex
       lock,  in  particular  a  mutex  that  is  not  within   a
       ThreadTable.   New,  independent  mutexes  can  simply  be
       defined with a  static  or  initialized  declaration.  For

       ThreadMutex global_mutex = ThreadNoId;

       ThreadMutexLock repeatedly polls and waits (with usleep())
       until the claim is  successful,  when  zero  is  returned.
       THREAD_NO_ID  is  returned  if  the specified thread id is
       ThreadNoId, and THREAD_LOCKED is returned if the specified
       thread  already  holds  the  mutex  lock. A memory barrier
       instruction is executed after the mutex is claimed, so the
       program  delays  until  all  store  instructions have completed,
 so the critical section will be safe in a  Symmetric
 Multi-Processor (SMP) system. The ThreadMutexLock routine
 is too intrusive when the procedures in  some  system
       libraries  are  instrumented, because it calls usleep; so,
       it should not be  used  in  objects  for  which  ThreadExcludeObj
  returns  a  non-zero  value or in procedures for
       which ThreadExcludeProc  returns  a  non-zero  value.  The
       pthread_mutex_lock(3) routine and the pthread_mutex_t type
       mutexes it supports should not be used  in  analysis  routines;
 neither should any other pthread_* routines.

       The ThreadMutexUnLock routine releases the specified mutex
       lock and executes a memory barrier  to  end  the  critical

       The  ThreadAddr  routine  returns the address of the mutex
       that protects the per-thread data for the specified thread
       id in the specified table.

       The  ThreadLockedAdd  routine provides a thread-safe, SMPsafe,
 add operation. It returns the value that the counter
       had  before  the  addition.  By casting to and from signed
       types, signed (for example, negative) values and  subtraction
  can  be achieved. It ensures that attempts to increment
 the counter are serialized. When an Atom tool's analysis
 routine only needs to increment one counter (or a set
       of counters that can be allowed to become  out  of  sync),
       use of this procedure lets you avoid the need for the more
       complex, slower, and more  intrusive  mutex  locks  around
       critical  sections. For example, it can be used for simple
       analysis of objects that  ThreadExcludeObj  identifies  as
       unsafe for analysis with the other Thread* services.


       Creating thread-safe replacement routines may also require
       the disabling  of  pthread  cancellation  points.  If  the
       replacement  routine  calls  any routine that is a pthread
       cancellation point, then disabling of pthread cancellation
       is recommended to avoid deadlock. All I/O calls are potential
 cancellation points.

       Hooks have been provided in libpthread.so  to  allow  this
       disabling.    The   libpthread   initialization   routines
       __pthreadAtomInit must be instrumented to allow the application
     addresses     of    __pthreadAtomDisable    and
       __pthreadAtomRestore to be set up before  any  pthread  is
       created, but after libpthread is loaded.

       Xlates are used to get the run-time application address of
       these routine.  At the beginning of an  analysis  routine,
       __pthreadAtomDisable  is  executed  by means of a function
       pointer.   At   the   end   of   the   analysis   routine,
       __pthreadAtomRestore  is also executed by means of a function
 pointer.  This ensures that no thread  will  be  cancelled
  while  in  an  analysis  routine and waiting for a

       Sample instrumentation code for disabling pthread  cancellation:

       Xlate  *      xlate; PlaceType   place = ProcBefore; Obj *
       disable_obj;   Entry   *       disable_entry=0;   Obj    *
       restore_obj;    Entry   *       restore_entry=0;   Obj   *
       init_obj; Proc *      init_proc=0;

       xlate   =    CreateXlate(obj,2);    init_obj    =    FindObj("__pthreadAtomInit");
    if    (init_obj    &&   IsObjBuilt(init_obj))

                 init_proc  =  FindProc(init_obj,  "__pthreadAtomInit");

       disable_obj  =  FindObj("__pthreadAtomDisable");  if (disable_obj
 && IsObjBuilt(disable_obj))
                 disable_entry      =      FindEntry(disable_obj,
       "__pthreadAtomDisable"); if (disable_entry) {
                 restore_obj = FindObj("__pthreadAtomRestore");
                 if (restore_obj && IsObjBuilt(restore_obj))
                     restore_entry            =           FindEntry(restore_obj,"__pthreadAtomRestore");

       AddXlateEntry(xlate, disable_entry);  AddXlateEntry(xlate,
       restore_entry);        AddCallProc(init_proc,       place,
       "set_repl_cancel_addr", xlate);

       Sample analysis code for initialization of pthread cancellation
 disabling and restoration:

       void set_repl_cancel_addr(XLATE *xlate) {
              unsigned long       func_addr;

              func_addr = XlateAddr(xlate, 0);
              repl_disable = (long (*)(void))func_addr;
              func_addr = XlateAddr(xlate,1);
              repl_restore = (void (*)(long))func_addr; }

       Sample  replacement  routine  that  disables  and restores
       pthread cancellation:

       void repl_routine(void) {
             long state;

             if (repl_disable)
                 state = (*repl_disable)();
                  * do something here.
             if (repl_restore)
                 (*repl_restore)(state); }

RETURN VALUES    [Toc]    [Back]

       A NULL pointer,  the  null  thread  id  ThreadNoId,  or  a
       nonzero ThreadStatus error code indicates failure (or true
       for logical functions), as described above.

FILES    [Toc]    [Back]

       Header  file  containing  external  definitions  of   Atom
       instrumentation  routines  Header file containing external
       definitions of Atom analysis  routines  Annotated  example
       sources  for a simple Atom tool that demonstrates a use of
       Atom's Thread routines to support analysis of applications
       that  fork  and  handle  signals in either a threaded or a
       non-threaded environment

SEE ALSO    [Toc]    [Back]

       Commands: atom(1)

       Functions:            atom_application_instrumentation(5),
       atom_application_navigation(5), atom_application_query(5),
       atom_application_symbols(5),     atom_description_file(5),
       atom_instrumentation_routines(5),      atom_object_management(5), AnalHeapBase(5), Xlate(5)

       Programmer's Guide

[ Back ]
 Similar pages
Name OS Title
getservent_r Tru64 Get a services file entry from the /etc/services file.
getservent Tru64 Get a services file entry from the /etc/services file.
nfssvc FreeBSD NFS services
nfssvc OpenBSD NFS services
nfssvc NetBSD NFS services
DtHelp HP-UX help services definitions
crypto_kdispatch OpenBSD API for cryptographic services in the kernel
crypto_register OpenBSD API for cryptographic services in the kernel
crypto_unregister OpenBSD API for cryptographic services in the kernel
inetd Tru64 Internet services daemon
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service