*** UNIX MANUAL PAGE BROWSER ***

Thread(5) File Formats Manual Thread(5) NAME Thread, ThreadExcludeObj, ThreadExcludeProc, ThreadExitCall, Thread- ForkCall, ThreadGetId, ThreadIsInternal, ThreadTableInit, ThreadTable- Lock, ThreadTableUnlock, ThreadTableFree, ThreadLookup, ThreadUnlock, ThreadRemove, ThreadForeach, ThreadMutexPoll, ThreadMutexLock, Thread- MutexUnlock, ThreadAddr, ThreadLockedAdd - Atom services used to de- velop 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 ); 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 analysis routine that is to be called just before a thread ter- minates. 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 Thread- TableInit(). Unique identification number for a thread, as pro- vided 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 it- eration callback function "proc" via its fourth argument. Pro- cedure to be called for each thread that has data in the speci- fied 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 Atom's Thread* routines help you write thread-safe analysis routines, for applications that use pthread_create and other DECthreads services. 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 li- braries. The ThreadExitCall routine instruments the specified object with a call to the named analysis routine at the point where the current thread is just about to terminate, if this is the object containing that point. ThreadExitCall returns a non-zero value if a call to the analysis rou- tine was inserted. The analysis routine must be defined with no argu- ments in a preceding AddCallProto call. If ThreadExitCall does insert a call, the object needs to be written out even if ThreadExcludeObj in- dicates that it should not be instrumented in general. A tool need not instrument the thread-termination point if it has no need to do so. A typical use of a thread-termination analysis routine is to write out a per-thread data file and free any per-thread analysis data. See the prof example referenced in the FILES section. The ThreadForkCall routine instruments the specified object with calls to the named analysis routines before and after any fork(2) or vfork(2) system-call instruction (usually in libc). ThreadForkCall returns a non-zero value if calls to the analysis routines were inserted. The analysis routines must be defined with no arguments in a preceding Add- CallProto call. If any analysis routines in the tool claim mutexes, the fork analysis routines need to unlock the mutexes in order to avoid deadlock in the child process. See the prof example referenced in the FILES section. 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 re- turned 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 ex- ample: 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 de- lays until all store instructions have completed, so the critical sec- tion 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 ex- ecutes 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 in- crement 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. RETURN VALUES A NULL pointer, the null thread id ThreadNoId, or a non-zero 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) AtomTools: hiprof(5), pixie(5), third(5) Functions: atom_application_instrumentation(5), atom_application_navi- gation(5), atom_application_resolvers(5), atom_application_query(5), atom_description_file(5), atom_object_management(5), atom_instrumenta- tion_routines(5), AnalHeapBase(5), Xlate(5) Programmer's Guide Thread(5)