The debugging information in this appendix is specific to applications
that use the POSIX Threads Library.
C.1 Using PTHREAD_CONFIG
During initialization of the Threads Library run-time environment, the
environment variable (on Tru64 UNIX systems) or logical symbol (on
OpenVMS systems), if defined, is used to set static options for the
multithreaded program. You can set
to assist you in debugging a Threads Library application.
C.1.1 Major and Minor Keywords
As summarized in Table C-1, PTHREAD_CONFIG takes "major keywords" as arguments. Use a "minor keyword" to specify a value for each major keyword.
|Major keyword||Minor keyword||Meaning|
|dump=||file-path||Path of bugcheck file (OpenVMS only)|
|meter=||condition||Meter condition variable operations|
|mutex||Meter mutex operations|
|Record thread greatest stack extent|
|all||Meter all available operations|
|width=||bugcheck_output_width||Width of output from bugcheck output|
When setting PTHREAD_CONFIG , use a semicolon to separate major keyword expressions and use a comma to separate minor keyword values. For example, using DCL under OpenVMS, you can set PTHREAD_CONFIG as follows:
$ define PTHREAD_CONFIG "meter=(stack,mutex);dump=/tmp/dump-d.dmp;width=132"
Metering tells the Threads Library to collect statistical and historical information about the use of synchronization objects within your program. This affects all synchronization within the program, including that within the Threads Library itself and any other libraries that use threads. Therefore, metering provides a very powerful tool for debugging multithreaded code.
To enable metering, define PTHREAD_CONFIG prior to running any threaded application. The variable should have a value of meter=all to enable metering. This causes the Threads Library to gather and record statistics and history information for all synchronization operations.
Programs running in metered mode are somewhat slower than unmetered programs. Also, normal mutexes that are metered can behave like errorcheck mutexes in many ways. This does not affect the behavior of correct programs, but you should be aware of some differences between normal and errorcheck mutexes. The most important difference is that normal mutexes do not report a number of usage errors, while errorcheck mutexes do.
Because it can be expensive to detect these conditions, a normal mutex may not always report these errors. Regardless of whether the program seems to work correctly under these circumstances, the operations are illegal. A metered normal mutex will report these errors under more circumstances than will an unmetered normal mutex.
We recommend Visual Threads to debug Threads Library applications on
Tru64 UNIX systems. Refer to the online Visual Threads documentation
for more information.
C.3 Using Ladebug on Tru64 UNIX Systems
The Compaq Ladebug debugger provides commands to display the state of threads, mutexes, and condition variables.
Using the Ladebug commands, you can examine core files and remote debug sessions, as well as run processes.
The basic commands are:
Refer to the Ladebug documentation for further details.
C.4 Debugging Threads on OpenVMS Systems
This section presents particular topics that relate to debugging a
multithreaded application under OpenVMS.
C.4.1 Display of Stack Trace from Unhandled Exception
When a program incurs an unhandled exception, a stack trace is produced that shows the call frames from the point where the exception was raised or, if TRY / CATCH , TRY / FINALLY , or POSIX cleanup handlers are used, from the point where it was last reraised to the bottom of the stack.
This appendix presents information that helps you migrate existing programs and applications that use the Compaq proprietary CMA (or cma) interface to use the pthread interface, based on the IEEE POSIX 1003.1c-1995 standard.
In future releases, the cma interface will continue to exist and be supported, but it will no longer be documented or enhanced. Therefore, it is recommended that you port your cma-based programs and applications to the pthread interface as soon as possible. The pthread interface is the most portable, efficient, and robust multithreading run-time library offered by Compaq.
The pthread interface differs significantly from the cma interface, though there are many similarities between the functions that individual routines perform. This section gives hints about the relationship between the two sets of routines, to assist you in migrating applications.
Note that routines whose names have the _np suffix are not portable---that is, the routine might not be available except in the POSIX Threads Library.
You should include the C language
header file for prototypes of the pthread routines.
D.2 cma Handles
A cma handle is storage, similar to a pointer, that refers to a specific Threads Library object (thread, mutex, condition variable, queue, or attributes object).
Handles are allocated by the user application. They can be freely copied by the program and stored in any class of storage; objects are managed by the Threads Library.
In the cma interface, because objects are accessed only by handles, you can think of the handle as if it were the object itself. Threads Library objects are accessed by handles (rather than pointers), because handles allow for greater robustness and portability. Handles allow the Threads Library to detect the following types of run-time errors:
Handles are not supported in the pthread interface.
Although this provides less robustness due to more limited error
checking, it allows better performance by decreasing memory use and
memory access. (That is, handles result in pointers to pointers.)
D.3 Interface Routine Mapping
As summarized in Table D-1, many cma routines perform functions nearly identical to corresponding routines in the pthread interface. The syntax and semantics differ, but the similarities are also notable.
|cma Routine||pthread Routine||Notes|
|cma_alert_disable_asynch()||pthread_setcancelstate() / pthread_setcanceltype()|
|cma_alert_disable_general()||pthread_setcancelstate() / pthread_setcanceltype()|
|cma_alert_enable_asynch()||pthread_setcancelstate() / pthread_setcanceltype()|
|cma_alert_enable_general()||pthread_setcancelstate() / pthread_setcanceltype()|
|cma_alert_restore()||pthread_setcancelstate() / pthread_setcanceltype()|
|cma_handle_assign()||none||Use Language assignment operator.|
(Note: pthread_key_delete() is available as well.)
Notice that the cma routine
requires the time argument expiration to be specified in local
time; whereas the pthread routine
requires the time argument abstime to be specified in
Universal Coordinated Time (UTC).
D.4 New pthread Routines
The following are pthread interface routines that have no functional similarities in the cma interface:
pthread_atfork() (Tru64 UNIX only)
pthread_kill() (Tru64 UNIX only)
All pthread_rwlockattr_ and pthread_rwlock_ routines
pthread_sigmask() (Tru64 UNIX only)