Updated: 11 December 1998 |
Guide to DECthreads
Previous | Contents | Index |
This appendix presents information that helps you migrate existing programs and applications that use the Compaq proprietary DECthreads CMA (or cma) interface to use the DECthreads pthread interface, based on the IEEE POSIX 1003.1c-1995 standard.
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 Compaq. |
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:
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.
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_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:
This appendix provides migration information for the routines in the DECthreads POSIX 1003.4a/Draft 4 (or d4) interface.
Applications that use the DECthreads d4 routines require significant modification to be migrated to the pthread interface described in Part 2. |
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.
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() |
Except for the return value, the following routines in the DECthreads d4 interface have no changes to syntax in the DECthreads pthread interface:
The following routines have no changes in syntax or return value:
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.
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-3 shows routines in the DECthreads d4 interface that have a corresponding pthread routine that does not support the obsolete d4-style datatypes. These datatypes were documented for previous releases of DECthreads.
If your original code used the standard DECthreads datatypes, then this migration requirement might not impact your code.
New Standard Datatype Syntax | Nonstandard Datatype Syntax |
---|---|
void
pthread_cleanup_push(
void (* routine)(void *), void * arg) |
int
pthread_cleanup_push(
pthread_cleanup_t * routine, pthread_addr_t arg) |
int
pthread_create(
pthread_t * thread, const pthread_attr_t * attr, void *(* start_routine)(void *), void * arg) |
int
pthread_create(
pthread_t * thread, pthread_attr_t attr, pthread_startroutine_t start_routine, pthread_addr_t arg) |
int
pthread_exit(
void * value_ptr) |
int
pthread_exit(
pthread_addr_t status) |
void *
pthread_getspecific(
pthread_key_t key) |
int
pthread_getspecific(
pthread_key_t key, pthread_addr_t * value) |
int
pthread_join(
pthread_t thread, void ** value_ptr) |
int
pthread_join(
pthread_t thread, pthread_addr_t * status) |
int
pthread_once(
pthread_once_t * once_control, void (* init_routine)(void)) |
int
pthread_once(
pthread_once_t * once_block, pthread_initroutine_t init_routine) |
int
pthread_setspecific(
pthread_key_t key, const void * value) |
int
pthread_setspecific(
pthread_key_t key, pthread_addr_t value) |
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
6101PRO_032.HTML
|