Thread(5) File Formats Manual Thread(5)
NAME
Thread, ThreadExcludeObj, ThreadExcludeProc, ThreadExitCall, ThreadForkCall, ThreadGetId, ThreadIsInternal, ThreadTableInit, ThreadTable-
Lock, ThreadTableUnlock, ThreadTableFree, ThreadLookup, ThreadUnlock, ThreadRemove, ThreadForeach, 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 ); 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 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
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. Sug-
gested 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
Atom's Thread* routines help you write thread-safe analysis routines, for applications that use pthread_create and other DECthreads ser-
vices.
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
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 libraries.
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
routine was inserted. The analysis routine must be defined with no arguments in a preceding AddCallProto call. If ThreadExitCall does
insert a call, the object needs to be written out even if ThreadExcludeObj indicates 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 AddCallProto 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
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 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 on.
The ThreadRemove routine breaks the connection between the thread id and its data in the thread table, for example when a thread termi-
nates. 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 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 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 call-
ing 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. Peri-
ods 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 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 bar-
rier 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 section.
The ThreadAddr routine returns the address of the mutex that protects the per-thread data for the specified thread id in the specified ta-
ble.
The ThreadLockedAdd routine provides a thread-safe, SMP-safe, 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.
RETURN VALUES
A NULL pointer, the null thread id ThreadNoId, or a non-zero ThreadStatus 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 demonstrates 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_navigation(5), atom_application_resolvers(5), atom_application_query(5),
atom_description_file(5), atom_object_management(5), atom_instrumentation_routines(5), AnalHeapBase(5), Xlate(5)
Programmer's Guide
Thread(5)