D.1.3 Running DECthreads in Metered Mode

Metering tells DECthreads to collect statistical and historical information on the use of synchronization objects within your program. This affects all synchronization within the program, including that within DECthreads itself and any other libraries that may use threads. Therefore, metering provides a very powerful tool for debugging multithreaded code.

To enable metering, define the environment variable (or OpenVMS logical name) PTHREAD_CONFIG prior to running any threaded application. The variable (or logical name) should have a value of "meter=all" to enable metering. This causes DECthreads to gather and record statistics and history information for all synchronization operations. Additionally, when running in metered mode DECthreads "poisons" all thread stacks (except the main thread stack) with a specific pattern. When using the thread -f or stack command in pthread_debug, DECthreads computes the number of bytes actually modified by the program on each stack.

Programs running in metered mode are somewhat slower than unmetered programs. Also, metered "normal" mutexes behave like "errorcheck" mutexes in many ways. This does not affect the behavior of correct programs, but there are some differences between normal and errorcheck mutexes of which you need to be aware. The most important difference is that normal mutexes do not report a number of usage errors, while errorcheck mutexes do.

The following operations are illegal and are always reported as errors when used on errorcheck mutexes, but may not be reported for non-metered "normal" mutexes:

• Locking a mutex in one thread and then unlocking it in another thread

• Unlocking a mutex that is not currently locked

• Relocking a mutex that the thread already owns

Since 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 a normal mutex that is not metered.