ThreadTableInit man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

Thread(5)							     Thread(5)

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

SYNOPSIS
       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  compati‐
       bility: 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 ThreadTableLock(
	       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  ThreadMut‐
       exPoll(
	       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
       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 anal‐
	      ysis  routine  that  is to be called just before a thread termi‐
	      nates.  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 num‐
	      ber  of  the  thread that does hold it.  Any unsigned long vari‐
	      able.  Any unsigned long value.

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

   Instrumentation Services
       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 Thread‐
       ForkCall.

       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
       libraries.

       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 Thread‐
       CreationObj  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
       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 DEC‐
       threads. Such threads are usually not profiled.

       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  Thread‐
       Lookup 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 num‐
       ber  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	speci‐
       fied;  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 on.

       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 ta‐
       ble's per-thread data, then ThreadRemove must be called	between	 calls
       to ThreadLookup (with THREAD_LOCK specified) and ThreadUnlock.

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

       The ThreadTableLock routine locks every current and future thread asso‐
       ciated  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 instru‐
       mented 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 partic‐
       ular a mutex that is not within a ThreadTable. New, independent mutexes
       can  simply  be	defined	 with a static or initialized declaration. For
       example:

       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;  nei‐
       ther should any other pthread_* routines.

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

       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, SMP-safe, add oper‐
       ation. 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 rou‐
       tine 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 analy‐
       sis of objects that ThreadExcludeObj identifies as unsafe for  analysis
       with the other Thread* services.

THREAD-SAFE REPLACEMENT ROUTINES
       Creating	 thread-safe  replacement  routines  may also require the dis‐
       abling 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  instru‐
       mented  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 rou‐
       tine.  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 resource.

       Sample instrumentation code for disabling pthread cancellation:

       Xlate *	   xlate; PlaceType   place =  ProcBefore;  Obj	 *	  dis‐
       able_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 && IsOb‐
       jBuilt(disable_obj))
		 disable_entry	=  FindEntry(disable_obj,   "__pthreadAtomDis‐
       able"); if (disable_entry) {
		 restore_obj = FindObj("__pthreadAtomRestore");
		 if (restore_obj && IsObjBuilt(restore_obj))
		     restore_entry  =  FindEntry(restore_obj,"__pthreadAtomRe‐
       store"); }

       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  dis‐
       abling 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 cancella‐
       tion:

       void repl_routine(void) {
	     long state;

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

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

FILES
       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	demon‐
       strates a use of Atom's Thread routines to support analysis of applica‐
       tions that fork and handle signals in  either  a	 threaded  or  a  non-
       threaded environment

SEE ALSO
       Commands: atom(1)

       Functions:  atom_application_instrumentation(5), atom_application_navi‐
       gation(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

								     Thread(5)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net