3.7 DECthreads Error Reporting

DECthreads can detect some of the following types of errors:

• Application programming interface (API) errors can occur when the program specifies an invalid parameter or attempts an inappropriate operation on some DECthreads object.

• Internal errors can occur when DECthreads determines that internal information has become corrupted to the point where it cannot continue operation.

API errors are reported in different ways by the various DECthreads interfaces:

• The POSIX 1003.1c (pthread) interface returns an integer value indicating the type of error.

• The cma interface raises exceptions to indicate error conditions.

DECthreads internal errors result in a bugcheck. DECthreads writes a message to the current error device (UNIX stderr or OpenVMS SYS$ERROR) summarizing the problem, and creates a file containing more detailed information. By default, the file is named pthread_ dump.log and is created in the current default directory. You can redirect the information to a different file by using the PTHREAD_ CONFIG dump option.

If DECthreads cannot create the specified file when it performs the bugcheck, it will try to create the default file. If it cannot create the default file, it will write the detailed information to the error device.

The header message written to the error device starts with a line reporting that DECthreads has detected an internal problem and that it is terminating execution. It also includes the version of the DECthreads library. It will look something like the following:

%DECthreads bugcheck (version V3.13-180), terminating execution.

The subsequent line is the reason for the failure, and the final line written to the error device (usually) is the location of the detailed state information, as in the following example:

% Dumping to pthread_dump.log

The detailed information file contains information you can get from the pthread_debug() interface. This information is usually necessary to track down the problem. If you submit a problem report involving a DECthreads bugcheck, please include this information file along with sample code and output.

The fact that DECthreads terminated the process with a bugcheck can mean that some subtle problem in DECthreads has been uncovered. However, DECthreads does not check for all possible API errors, and there are a number of ways in which improper application code can result in a DECthreads bugcheck.

One common example is the use of any mutex operation or certain condition variable operations from within an interrupt routine (UNIX signal handler or OpenVMS AST routine). This type of programming error most commonly results in bugchecks reporting "enter_kernel: deadlock" or "Can't find null thread". To prevent this error, avoid using any condition variables operations other than pthread_cond_ signal_int_np from an interrupt routine (or the equivalent routines in other APIs).

In addition, DECthreads maintains a variety of state information in memory which is writable by user mode code. Therefore, it is possible for applications to accidentally modify DECthreads state by writing through invalid pointers, which can result in a bugcheck or other undesirable behavior.