Guide to DECthreads

threads-number

One or more sequence numbers separated by spaces. If specified, only those objects whose sequence numbers are listed are displayed. Each argument that does not begin with "-" is interpreted as the sequence number of an object.

Table D-6 lists the valid qualifier argument switches.

Table D-6 Qualifiers for threads Command
Qualifier Description

-1 (Digit "1") Display threads in a one-line tabular format.

-a Include internal threads created by DECthreads.

-b List threads that are currently blocked (waiting on a condition variable or attempting to lock a mutex).

-c List the threads that are currently running. (On a uniprocessor implementation, there is only one thread at any time.)

-d List the threads that have been detached. ( cma_detach() or pthread_detach() called for the thread, or it was created with the detached attribute set.)

-f Give full information on threads. Essentially, this sets all the "display" selection flags. Always use -f and -a qualifiers when submitting debug output as a part of a problem report.

-h List the threads that have been held using the tset -h command.

-k Display the thread-specific data values associated with each selected thread.

-l List threads that own mutexes. (Normal mutexes are not included unless metering is enabled.)

-m Display only the current thread.

-n List the threads that have not been held.

-o Select specific output fields. For example, thread -o res.

b : blocking information
c : cancel status
i : "internal" state
k : tsd keys
l : show owned mutexes (if known)
m : miscellaneous state
r : realtime scheduling information
s : stack information
v : virtual processor state

-r List the threads that are ready to run. (They are not blocked or terminated, but cannot currently run because the processor is busy.)

-s policy
[ operator priority] List threads with particular scheduling policies and priorities. The policy field is required and specifies the name of a scheduling policy: fifo, rr, foreground, background, ada_rtb, ada_low, or idle. The operator field specifies a C relational operator that is to be applied in comparing a thread's priority against the -s criteria: :=,=, !=, >, <, >=, <=. Finally, the priority field is a priority value within the priority range for the specified scheduling policy; the keywords min (minimum priority), mid (midrange priority), and max (maximum priority) are accepted as well as integer values.
The operator and priority fields are optional. If both are omitted, all threads with the specified scheduling policy will be selected.

-t List the threads that have terminated but have not yet been detached. (They are waiting for another thread to join with them.)

**Table D-6 Qualifiers for threads Command**
Qualifier	Description
-1	(Digit "1") Display threads in a one-line tabular format.
-a	Include internal threads created by DECthreads.
-b	List threads that are currently blocked (waiting on a condition variable or attempting to lock a mutex).
-c	List the threads that are currently running. (On a uniprocessor implementation, there is only one thread at any time.)
-d	List the threads that have been detached. ( cma_detach() or pthread_detach() called for the thread, or it was created with the detached attribute set.)
-f	Give full information on threads. Essentially, this sets all the "display" selection flags. Always use -f and -a qualifiers when submitting debug output as a part of a problem report.
-h	List the threads that have been held using the tset -h command.
-k	Display the thread-specific data values associated with each selected thread.
-l	List threads that own mutexes. (Normal mutexes are not included unless metering is enabled.)
-m	Display only the current thread.
-n	List the threads that have not been held.
-o	Select specific output fields. For example, thread -o res. b : blocking information c : cancel status i : "internal" state k : tsd keys l : show owned mutexes (if known) m : miscellaneous state r : realtime scheduling information s : stack information v : virtual processor state
-r	List the threads that are ready to run. (They are not blocked or terminated, but cannot currently run because the processor is busy.)
-s policy [ operator priority]	List threads with particular scheduling policies and priorities. The policy field is required and specifies the name of a scheduling policy: fifo, rr, foreground, background, ada_rtb, ada_low, or idle. The operator field specifies a C relational operator that is to be applied in comparing a thread's priority against the -s criteria: :=,=, !=, >, <, >=, <=. Finally, the priority field is a priority value within the priority range for the specified scheduling policy; the keywords min (minimum priority), mid (midrange priority), and max (maximum priority) are accepted as well as integer values. The operator and priority fields are optional. If both are omitted, all threads with the specified scheduling policy will be selected.
-t	List the threads that have terminated but have not yet been detached. (They are waiting for another thread to join with them.)

D.1.4.10 Versions Command

The versions command displays the current version of DECthreads, the type of operating system and hardware for which it was built, and the current operating system version.

Format:

versions

D.2 Using Ladebug on Digital UNIX

The Digital Ladebug debugger provides commands to display the state of threads, mutexes, and condition variables, without using the built-in DECthreads debug facility.

Using the Ladebug commands, you can examine core files and remote debug sessions, as well as run processes.

The basic commands are:

threadn --- Sets the current thread context to n.
show thread[n ...] --- Displays thread state (more information displayed if $verbose=1)
show mutex[n ...] --- Display mutex state.
show condition[n ...] --- Display condition variable state.

Refer to the Ladebug documentation for further details.

D.3 Debugging Threads on OpenVMS Systems

This section presents particular topics that relate to debugging a multithreaded application under OpenVMS.

D.3.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 DECthreads TRY/CATCH, TRY/FINALLY, or POSIX "push-pop" handlers are used, from the point where it was last reraised to the bottom of the stack.

D.4 Debugging Threads on Windows NT Systems

The WinDbg Debugger, provided with the Windows NT Software Development Kit (SDK), provides support for debugging a threaded program. When working with DECthreads in WinDbg, be aware that terminating a thread with pthread_exit(), cma_exit_normal(), or cma_exit_error() raises an exception as a normal part of the exiting process. Unless you explicitly tell WinDbg to ignore this exception, it catches the exception and stops execution. To allow the thread to exit properly and your application to continue, use the WinDbg gn (go not handled) command. This command tells WinDbg to ignore the exception.

WinDbg also stops at each DECthreads exception block for this exception and has to be continued using the WinDbg gn command until the thread's stack is completely unwound. The exception used by DECthreads for thread rundown is 0xC1380034.

DECthreads also generates an exception in a thread as a normal part of thread cancelation. When canceling a thread with pthread_cancel() or cma_thread_alert(), an exception value of 0xC1380034 is raised. This exception should be allowed to propagate all the way to the base of the thread's stack. If WinDbg halts execution of the program and indicates that this exception is being raised, use the WinDbg gn command to allow the exception to continue.

Appendix E
Migrating from the cma Interface

This appendix presents information that helps you migrate existing programs and applications that use the Digital-proprietary DECthreads CMA (or cma) interface to use the DECthreads pthread interface, based on the IEEE POSIX 1003.1c-1995 standard.

Note
In future DECthreads 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 DECthreads pthread interface is the most portable, efficient, and robust multithreading run-time library offered by Digital.

E.1 Overview

The DECthreads 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 DECthreads.

You need not prototype the pthread routines if you include the C language pthread.h header file.

E.2 cma Handles

A cma handle is storage, similar to a pointer, that refers to a specific DECthreads 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 DECthreads.

In the cma interface, because objects are accessed only by handles, you can think of the handle as if it were the object itself. DECthreads objects are accessed by handles (rather than pointers), because handles allow for greater robustness and portability. Handles allow DECthreads to detect the following types of run-time errors:

Using an uninitialized handle
Using a corrupted handle
Using a handle whose object no longer exists (a dangling handle)

Handles are not supported in the DECthreads 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.)

E.3 Interface Routine Mapping

As summarized in Table E-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.

Table E-1 Corresponding cma and pthread Routines
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_alert_test() pthread_testcancel()

cma_attr_create() pthread_attr_init()

cma_attr_delete() pthread_attr_destroy()

cma_attr_get_guardsize() pthread_attr_getguardsize_np()

cma_attr_get_inherit_sched() pthread_attr_getinheritsched()

cma_attr_get_mutex_kind() pthread_mutexattr_gettype_np()

cma_attr_get_priority() pthread_attr_setsched_param()

cma_attr_get_sched() pthread_attr_getschedpolicy()

cma_attr_get_stacksize() pthread_attr_getstacksize()

cma_attr_set_guardsize() pthread_attr_setguardsize_np()

cma_attr_set_inherit_sched() pthread_attr_setinheritsched()

cma_attr_set_mutex_kind() pthread_mutexattr_settype_np()

cma_attr_set_priority() pthread_attr_setsched_param()

cma_attr_set_sched() pthread_attr_setschedpolicy()

cma_attr_set_stacksize() pthread_attr_setstacksize()

cma_cond_broadcast() pthread_cond_broadcast()

cma_cond_create() pthread_cond_init()

cma_cond_delete() pthread_cond_destroy()

cma_cond_signal() pthread_cond_signal()

cma_cond_signal_int() pthread_cond_signal_int_np()

cma_cond_timed_wait() pthread_cond_timedwait()

cma_cond_wait() pthread_cond_wait()

cma_debug() pthread_debug()

cma_debug_cmd() pthread_debug_cmd()

cma_delay() pthread_delay_np()

cma_handle_assign() none Use Language assignment operator.

cma_handle_equal() pthread_equal()

cma_init() none Not necessary.

cma_key_create() pthread_key_create()
(Note: pthread_key_delete() is available as well.)

cma_key_get_context() pthread_getspecific()

cma_key_set_context() pthread_setspecific()

cma_lock_global() pthread_lock_global_np()

cma_mutex_create() pthread_mutex_init()

cma_mutex_delete() pthread_mutex_delete()

cma_mutex_lock() pthread_mutex_lock()

cma_mutex_try_lock() pthread_mutex_trylock()

cma_mutex_unlock() pthread_mutex_unlock()

cma_once() pthread_once()

cma_stack_check_limit_np()

cma_thread_alert() pthread_cancel()

cma_thread_bind_to_cpu() none

cma_thread_create() pthread_create()

cma_thread_detach() pthread_detach()

cma_thread_exit_error() pthread_exit() With Status.

cma_thread_exit_normal() pthread_exit() With Status.

cma_thread_get_priority() pthread_getschedparam()

cma_thread_get_sched() pthread_setschedparam()

cma_thread_get_self() pthread_self()

cma_thread_join() pthread_join()

cma_thread_set_priority() pthread_setschedparam()

cma_thread_set_sched() pthread_setschedparam()

cma_time_get_expiration() pthread_get_expiration_np()

cma_unlock_global() pthread_unlock_global_np()

cma_yield() pthread_yield()

**Table E-1 Corresponding cma and pthread Routines**
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_alert_test()	pthread_testcancel()
cma_attr_create()	pthread_attr_init()
cma_attr_delete()	pthread_attr_destroy()
cma_attr_get_guardsize()	pthread_attr_getguardsize_np()
cma_attr_get_inherit_sched()	pthread_attr_getinheritsched()
cma_attr_get_mutex_kind()	pthread_mutexattr_gettype_np()
cma_attr_get_priority()	pthread_attr_setsched_param()
cma_attr_get_sched()	pthread_attr_getschedpolicy()
cma_attr_get_stacksize()	pthread_attr_getstacksize()
cma_attr_set_guardsize()	pthread_attr_setguardsize_np()
cma_attr_set_inherit_sched()	pthread_attr_setinheritsched()
cma_attr_set_mutex_kind()	pthread_mutexattr_settype_np()
cma_attr_set_priority()	pthread_attr_setsched_param()
cma_attr_set_sched()	pthread_attr_setschedpolicy()
cma_attr_set_stacksize()	pthread_attr_setstacksize()
cma_cond_broadcast()	pthread_cond_broadcast()
cma_cond_create()	pthread_cond_init()
cma_cond_delete()	pthread_cond_destroy()
cma_cond_signal()	pthread_cond_signal()
cma_cond_signal_int()	pthread_cond_signal_int_np()
cma_cond_timed_wait()	pthread_cond_timedwait()
cma_cond_wait()	pthread_cond_wait()
cma_debug()	pthread_debug()
cma_debug_cmd()	pthread_debug_cmd()
cma_delay()	pthread_delay_np()
cma_handle_assign()	none	Use Language assignment operator.
cma_handle_equal()	pthread_equal()
cma_init()	none	Not necessary.
cma_key_create()	pthread_key_create() (Note: pthread_key_delete() is available as well.)
cma_key_get_context()	pthread_getspecific()
cma_key_set_context()	pthread_setspecific()
cma_lock_global()	pthread_lock_global_np()
cma_mutex_create()	pthread_mutex_init()
cma_mutex_delete()	pthread_mutex_delete()
cma_mutex_lock()	pthread_mutex_lock()
cma_mutex_try_lock()	pthread_mutex_trylock()
cma_mutex_unlock()	pthread_mutex_unlock()
cma_once()	pthread_once()
cma_stack_check_limit_np()
cma_thread_alert()	pthread_cancel()
cma_thread_bind_to_cpu()	none
cma_thread_create()	pthread_create()
cma_thread_detach()	pthread_detach()
cma_thread_exit_error()	pthread_exit()	With Status.
cma_thread_exit_normal()	pthread_exit()	With Status.
cma_thread_get_priority()	pthread_getschedparam()
cma_thread_get_sched()	pthread_setschedparam()
cma_thread_get_self()	pthread_self()
cma_thread_join()	pthread_join()
cma_thread_set_priority()	pthread_setschedparam()
cma_thread_set_sched()	pthread_setschedparam()
cma_time_get_expiration()	pthread_get_expiration_np()
cma_unlock_global()	pthread_unlock_global_np()
cma_yield()	pthread_yield()

Notice that the cma routine cma_cond_timed_wait() requires the time argument expiration to be specified in local time; whereas the pthread routine pthread_cond_timedwait() requires the time argument abstime to be specified in Universal Coordinated Time (UTC).

E.4 New pthread Routines

The following are pthread interface routines that have no functional similarities in the cma interface:

pthread_atfork()
(Digital UNIX only)
pthread_attr_getdetachstate()
pthread_attr_setdetachstate()
pthread_key_delete()
pthread_kill()
(Digital UNIX only)
pthread_sigmask()
(Digital UNIX only)

Appendix F
Migrating from the d4 Interface

This appendix provides migration information for the routines in the DECthreads POSIX 1003.4a/Draft 4 (or d4) interface.

Note
Applications that use the DECthreads d4 routines require significant modification to be migrated to the pthread interface described in Part 2.

F.1 Overview

Routines in the DECthreads pthread interface differ significantly from the original DECthreads POSIX 1003.4a/Draft 4 implementation. This section describes the major changes between the interfaces.

F.2 Error Status and Function Returns

The DECthreads pthread interface does not use the global variable errno. (Note that DECthreads provides a thread-specific errno for use by libraries and application code, but the DECthreads pthread interface does not write to it.)

If an error condition occurs, a pthread routine returns an integer value that indicates the type of error. For example, a call to the DECthreads d4 interface's implementation of pthread_cond_destroy() that returned a --1 and set errno to [EBUSY], returns [EBUSY] as the routine's return value in the pthread interface implementation.

On successful completion, most pthread interface routines return zero (0).

F.3 Replaced or Renamed Routines

Many routines in the DECthreads d4 interface have been replaced or renamed in the pthread interface, as shown in Table F-1.

Table F-1 pthread Routines That Replace d4 Routines
d4 Routine Replacement pthread Routine

pthread_attr_create() pthread_attr_init()

pthread_attr_delete() pthread_attr_destroy()

pthread_attr_set/getdetach_np() pthread_attr_set/getdetachstate()

pthread_attr_set/getprio() pthread_attr_set/getschedparam()

pthread_attr_set/getsched() pthread_attr_set/getschedpolicy()

pthread_condattr_create() pthread_condattr_init()

pthread_condattr_delete() pthread_condattr_destroy()

pthread_keycreate() pthread_key_create()

pthread_mutexattr_create() pthread_mutexattr_init()

pthread_mutexattr_delete() pthread_mutexattr_destroy()

pthread_mutexattr_get/setkind_np() pthread_mutexattr_get/settype_np()

pthread_setasynccancel() pthread_setcanceltype()

pthread_setcancel() pthread_setcancelstate()

pthread_set/getprio() pthread_set/getschedparam()

pthread_set/getscheduler() pthread_set/getschedparam()

pthread_yield() sched_yield()

**Table F-1 pthread Routines That Replace d4 Routines**
d4 Routine	Replacement pthread Routine
pthread_attr_create()	pthread_attr_init()
pthread_attr_delete()	pthread_attr_destroy()
pthread_attr_set/getdetach_np()	pthread_attr_set/getdetachstate()
pthread_attr_set/getprio()	pthread_attr_set/getschedparam()
pthread_attr_set/getsched()	pthread_attr_set/getschedpolicy()
pthread_condattr_create()	pthread_condattr_init()
pthread_condattr_delete()	pthread_condattr_destroy()
pthread_keycreate()	pthread_key_create()
pthread_mutexattr_create()	pthread_mutexattr_init()
pthread_mutexattr_delete()	pthread_mutexattr_destroy()
pthread_mutexattr_get/setkind_np()	pthread_mutexattr_get/settype_np()
pthread_setasynccancel()	pthread_setcanceltype()
pthread_setcancel()	pthread_setcancelstate()
pthread_set/getprio()	pthread_set/getschedparam()
pthread_set/getscheduler()	pthread_set/getschedparam()
pthread_yield()	sched_yield()

F.4 Routines with No Changes to Syntax

Except for the return value, the following routines in the DECthreads d4 interface have no changes to syntax in the DECthreads pthread interface:

pthread_attr_setinheritsched()
pthread_cancel()
pthread_cond_broadcast()
pthread_cond_destroy()
pthread_cond_signal()
pthread_cond_signal_int_np()
pthread_cond_timedwait()
pthread_cond_wait()
pthread_delay_np()
pthread_equal()
pthread_exit()
pthread_get_expiration_np()
pthread_join() (now detaches the thread)
pthread_mutex_destroy()
pthread_mutex_lock()
pthread_mutex_trylock()
pthread_mutex_unlock()
pthread_once()

The following routines have no changes in syntax or return value:

pthread_self()
pthread_testcancel()

Notice that the d4 routine pthread_cond_timedwait() requires the time argument abstime to be specified in local time; whereas the pthread routine pthread_cond_timedwait() requires the time argument abstime to be specified in Universal Coordinated Time (UTC).

F.5 Routines with Prototype or Syntax Changes

Table F-2 shows the routines in the DECthreads d4 interface that have changes to their argument syntax in the DECthreads pthread interface.

Table F-2 d4 Routines With Syntax Changes as pthread Routines
Old Syntax New Syntax

unsigned long pthread_attr_getguardsize_np(
pthread_attr_t attr) int pthread_attr_getguardsize_np(
const pthread_attr_t * attr,
size_t * guardsize)

int pthread_attr_getinheritsched(
pthread_attr_t attr) int pthread_attr_getinheritsched(
const pthread_attr_t * attr,
int * inheritsched)

unsigned long pthread_attr_getstacksize(
pthread_attr_t attr) int pthread_attr_getstacksize(
const pthread_attr_t * attr,
size_t * stacksize)

unsigned long pthread_attr_setguardsize_np(
pthread_attr_t * attr, long guardsize) int pthread_attr_setguardsize_np(
pthread_attr_t * attr,
size_t guardsize)

unsigned long pthread_attr_setstacksize(
pthread_attr_t * attr,
long stacksize) int pthread_attr_setstacksize(
const pthread_attr_t * attr,
size_t stacksize)

int pthread_cleanup_pop(
int execute) void pthread_cleanup_pop(
int execute)

int pthread_cond_init(
pthread_cond_t * cond,
pthread_condattr_t attr) int pthread_cond_init(
pthread_cond_t * cond,
pthread_condattr_t * attr)

int pthread_create(
pthread_t * thread,
pthread_attr_t attr,
pthread_startroutine_t start_routine,
pthread_addr_t arg) int pthread_create(
pthread_t * thread,
const pthread_attr_t * attr,
void* (* start_routine)(void *),
void * arg)

int pthread_detach(
pthread_t * thread) int pthread_detach(
pthread_t thread)

int pthread_getspecific(
pthread_key_t key, void ** value) void* pthread_getspecific(
pthread_key_t key)

void pthread_lock_global_np() int pthread_lock_global_np(void)

void pthread_unlock_global_np() int pthread_unlock_global_np(void)

int pthread_mutex_init(
pthread_mutex_t * mutex,
pthread_mutexattr_t attr) int pthread_mutex_init(
pthread_mutex_t * mutex,
const pthread_mutexattr_t * attr)

**Table F-2 d4 Routines With Syntax Changes as pthread Routines**
Old Syntax	New Syntax
unsigned long pthread_attr_getguardsize_np( pthread_attr_t attr)	int pthread_attr_getguardsize_np( const pthread_attr_t * attr, size_t * guardsize)
int pthread_attr_getinheritsched( pthread_attr_t attr)	int pthread_attr_getinheritsched( const pthread_attr_t * attr, int * inheritsched)
unsigned long pthread_attr_getstacksize( pthread_attr_t attr)	int pthread_attr_getstacksize( const pthread_attr_t * attr, size_t * stacksize)
unsigned long pthread_attr_setguardsize_np( pthread_attr_t * attr, long guardsize)	int pthread_attr_setguardsize_np( pthread_attr_t * attr, size_t guardsize)
unsigned long pthread_attr_setstacksize( pthread_attr_t * attr, long stacksize)	int pthread_attr_setstacksize( const pthread_attr_t * attr, size_t stacksize)
int pthread_cleanup_pop( int execute)	void pthread_cleanup_pop( int execute)
int pthread_cond_init( pthread_cond_t * cond, pthread_condattr_t attr)	int pthread_cond_init( pthread_cond_t * cond, pthread_condattr_t * attr)
int pthread_create( pthread_t * thread, pthread_attr_t attr, pthread_startroutine_t start_routine, pthread_addr_t arg)	int pthread_create( pthread_t * thread, const pthread_attr_t * attr, void* (* start_routine)(void ), void arg)
int pthread_detach( pthread_t * thread)	int pthread_detach( pthread_t thread)
int pthread_getspecific( pthread_key_t key, void ** value)	void* pthread_getspecific( pthread_key_t key)
void pthread_lock_global_np()	int pthread_lock_global_np(void)
void pthread_unlock_global_np()	int pthread_unlock_global_np(void)
int pthread_mutex_init( pthread_mutex_t * mutex, pthread_mutexattr_t attr)	int pthread_mutex_init( pthread_mutex_t * mutex, const pthread_mutexattr_t * attr)

  6493P018.HTM
  OSSG Documentation
  22-NOV-1996 13:20:24.14

Legal