This release of DECthreads includes interface definitions for the C programming language only. However, all DECthreads routines are callable from languages other than C. Your application must provide its own declarations for DECthreads routines in a manner appropriate to its programming language. These definitions should be modeled after the declarations in the C language pthread.h header file.
For backward compatibility, this version of DECthreads also supports
other interfaces that are not documented in this guide. See
Section 1.6.3.
1.6.1 Multithreading pthread Interface
This version of DECthreads offers one documented interface for multithreading capability. The pthread interface routines implement the IEEE Standard 1003.1c-1995, Portable Operating System Interface (or POSIX) Application Program Interface, also known as POSIX.1c. (More specifically, this interface is an extension to the 1003.1 Portable Operating System Interface standard rather than an independent interface specification.)
The DECthreads pthread implementation of the POSIX.1c standard is the primary multithreading interface in the DECthreads environment---that is, it is the most portable, efficient, and powerful multithreading interface supported by DECthreads.
Table 1-1 lists and summarizes functionally the DECthreads pthread interface routines.
The pthread interface contains routines grouped in the following functional categories:
The DECthreads pthread interface also provides routines that implement nonportable extensions to the POSIX.1c standard. These routines are grouped in these functional categories:
Note
Some routines in the pthread interface have a corresponding or similar routine in the tis interface. However, you should avoid specifying objects created under one DECthreads interface in calls to a different DECthreads interface.
Among the routines in the pthread interface that implement nonportable extensions to the POSIX.1c standard, are the routines in the DECthreads exception package. This package consists of a library and C language header file (pthread_exceptions.h) that implement a DECthreads-specific exception-handling facility. It is designed specifically for use with the DECthreads pthread interface. Chapter 5 describes the DECthreads exception package.
This guide also documents several routines that are not declared entries in the DECthreads pthread interface, but that have close affinity with its functionality. Examples are the sched_yield() and sigwait() routines. See the end of Table 1-1 for a list of these routines.
| Routine | Description |
|---|---|
| General Threads Routines | |
| pthread_atfork() | Declares fork handler routines to be called. |
| pthread_create() | Creates a thread object and thread. |
| pthread_detach() | Marks a thread object for deletion. |
| pthread_equal() | Compares one thread identifier to another thread identifier. |
| pthread_exit() | Terminates the calling thread. |
| pthread_join() | Causes the calling thread to wait for the termination of a specified thread and detach it. |
| pthread_kill() | Delivers a signal to a specified thread. |
| pthread_once() | Calls an initialization routine to be executed only once. |
| pthread_self() | Obtains the identifier of the calling thread. |
| pthread_sigmask() | Examines or changes the calling thread's signal mask. |
| Thread Attributes Object Routines | |
| pthread_attr_destroy() | Destroys a thread attributes object. |
| pthread_attr_getdetachstate() | Obtains the detachstate attribute from the specified thread attributes object. |
| pthread_attr_getguardsize() | Obtains the guardsize attribute of the specified thread attributes object. |
| pthread_attr_getinheritsched() | Obtains the inherit scheduling attribute from the specified thread attributes object. |
| pthread_attr_getschedparam() | Obtains the scheduling parameters for an attribute of the specified thread attributes object. |
| pthread_attr_getschedpolicy() | Obtains the scheduling policy attribute of the specified thread attributes object. |
| pthread_attr_getscope() | Obtains the contention-scope attribute of the specified thread attributes object. |
| pthread_attr_getstackaddr() | Obtains the stackaddr attribute of the specified thread attributes object. |
| pthread_attr_getstacksize() | Obtains the stacksize attribute of the specified thread attributes object. |
| pthread_attr_init() | Initializes a thread attributes object. |
| pthread_attr_setdetachstate() | Changes the detachstate attribute in the specified thread attributes object. |
| pthread_attr_setguardsize() | Changes the guardsize attribute of the specified thread attributes object. |
| pthread_attr_setinheritsched() | Changes the inherit scheduling attribute of the specified thread attributes object. |
| pthread_attr_setschedparam() | Changes the values of the parameters associated with the scheduling policy attribute of the specified thread attributes object. |
| pthread_attr_setschedpolicy() | Changes the scheduling policy attribute of the specified thread attributes object. |
| pthread_attr_setscope() | Changes the contention-scope attribute of the specified thread attributes object. |
| pthread_attr_setstackaddr() | Changes the stackaddr attribute in the specified thread attributes object. |
| pthread_attr_setstacksize() | Changes the stacksize attribute in the specified thread attributes object. |
| Thread Cancelation Routines | |
| pthread_cancel() | Allows a thread to request that it, or another thread, terminate execution. |
| pthread_cleanup_pop() | Removes a cleanup handler routine from the top of the cleanup stack and optionally executes it. |
| pthread_cleanup_push() | Establishes a cleanup handler routine to be executed when the thread exits or is canceled. |
| pthread_setcancelstate() | Changes the calling thread's cancelability state. |
| pthread_setcanceltype() | Changes the calling thread's cancelability type. |
| pthread_testcancel() | Requests delivery of any pending cancelation request to the calling thread. |
| Thread Priority, Concurrency, and Scheduling Routines | |
| pthread_getconcurrency() | Obtains the current concurrency level parameter for the process. |
| pthread_getschedparam() | Obtains the current scheduling policy and scheduling parameters of a thread. |
| pthread_setconcurrency() | Changes the current concurrency level parameter for the process. |
| pthread_setschedparam() | Changes the current scheduling policy and scheduling parameters of a thread. |
| Thread-Specific Data Routines | |
| pthread_getspecific() | Obtains the thread-specific data associated with the specified key. |
| pthread_key_create() | Generates a unique thread-specific data key. |
| pthread_setspecific() | Changes the thread-specific data value associated with the specified key for the calling thread. |
| pthread_key_delete() | Deletes a thread-specific data key. |
| Mutex Routines | |
| pthread_mutex_destroy() | Destroys a mutex. |
| pthread_mutex_init() | Initializes a mutex with attributes specified by the attributes argument. |
| pthread_mutex_lock() | Locks an unlocked mutex; if locked, the caller waits for the mutex to become available. |
| pthread_mutex_trylock() | Attempts to lock a mutex; returns immediately if mutex is already locked. |
| pthread_mutex_unlock() | Unlocks a locked mutex. |
| Mutex Attributes Object Routines | |
| pthread_mutexattr_init() | Initializes a mutex attributes object. |
| pthread_mutexattr_destroy() | Destroys a mutex attributes object. |
| pthread_mutexattr_gettype() | Obtains the mutex type attribute of a mutex attributes object. |
| pthread_mutexattr_settype() | Changes the mutex type attribute of a mutex attributes object. |
| Condition Variable Routines | |
| pthread_cond_broadcast() | Wakes all threads waiting on a condition variable. |
| pthread_cond_destroy() | Destroys a condition variable. |
| pthread_cond_init() | Initializes a condition variable. |
| pthread_cond_signal() | Wakes at least one thread that is waiting on a condition variable. |
| pthread_cond_timedwait() | Causes a thread to wait a specified period of time for a condition variable to be signaled or broadcasted. |
| pthread_cond_wait() | Causes a thread to wait for a condition variable to be signaled or broadcasted. |
| Condition Variable Attributes Object Routines | |
| pthread_condattr_destroy() | Destroys a condition variable attributes object. |
| pthread_condattr_init() | Initializes a condition variable attributes object. |
| Nonportable Extensions | |
|
pthread_delay_np()
pthread_get_expiration_np() pthread_getsequence_np() |
Thread execution routines |
|
pthread_attr_getguardsize_np()
pthread_attr_setguardsize_np() |
Thread attributes routines |
|
pthread_lock_global_np()
pthread_unlock_global_np() |
DECthreads global mutex routines |
|
pthread_mutexattr_gettype_np()
pthread_mutexattr_settype_np() |
Mutex attributes routines |
| pthread_cond_signal_int_np() | Condition variable routines |
|
pthread_attr_getname_np()
pthread_attr_setname_np() pthread_cond_getname_np() pthread_cond_setname_np() pthread_getname_np() pthread_key_getname_np() pthread_key_setname_np() pthread_mutex_getname_np() pthread_mutex_setname_np() pthread_setname_np() |
Object naming routines |
|
pthread_exc_get_status_np()
pthread_exc_matches_np() pthread_exc_report_np() pthread_exc_set_status_np() |
DECthreads exception object routines |
| Related Standard Routines | |
| sched_get_priority_max() | Returns the maximum priority for the specified scheduling policy. |
| sched_get_priority_min() | Returns the minimum priority for the specified scheduling policy. |
| sched_yield() | Notifies the scheduler that the calling thread is willing to release its processor to other threads of the same or higher scheduling precedence. |
| sigwait() | Suspends a calling thread until a signal arrives. |
1.6.1.1 Optionally Implemented POSIX.1c-1995 Routines
In this version of DECthreads, the pthread interface
does not support the following features that are specified in the
POSIX.1c standard:
The POSIX.1c standard directs DECthreads to provide the macros named
_POSIX_THREAD_PROCESS_SHARED,
_POSIX_THREAD_PRIO_PROTECT, and
_POSIX_THREAD_PRIO_INHERIT to report whether optionally
implemented routines are present.
1.6.2 Thread-Independent Services Interface
The DIGITAL-proprietary tis interface offers a set of thread-independent services. Use these routines to build software that performs processing that requires synchronization, but without requiring the use of threads. That is, use tis routines to build thread-safe code libraries whose routines can be called from either a single-threaded or multithreaded environment.
In the absence of threads, tis routines impose minimal overhead on the calling program. For instance, tis routines do not use interlocked instructions and memory barriers.
When threads are present, tis routines provide full support for DECthreads synchronization, such as synchronization objects and thread joining. Note that there are no tis routines for creating threads or thread objects, because that would have no meaning if called from a single-threaded environment.
The tis routines can be classified into these functional categories:
Note
Some routines in the pthread interface have a corresponding or similar routine in the tis interface.
Table 1-2 summarizies these groups of tis routines.
| Routine | Description |
|---|---|
| General Routines | |
| tis_once() | Calls a one-time initialization routine that can be executed. |
| tis_self() | Obtains the identifier of the calling thread. |
| Thread Cancelation Routines | |
| tis_setcancelstate() | Changes the calling thread's cancelability state. |
| tis_testcancel() | Creates a cancelation point in the calling thread. |
| Thread-Specific Data Key Routines | |
| tis_getspecific() | Obtains the data associated with the specified thread-specific data key. |
| tis_key_create() | Generates a unique thread-specific data key. |
| tis_key_delete() | Deletes a thread-specific data key. |
| tis_setspecific() | Changes the value associated with the specified thread-specific data key. |
| Mutex Routines | |
| tis_lock_global() | Locks the DECthreads global mutex. |
| tis_mutex_destroy() | Destroys the specified tis mutex object. |
| tis_mutex_init() | Initializes a tis mutex object. |
| tis_mutex_lock() | Locks the specified tis mutex, if unlocked. |
| tis_mutex_trylock() | Tries to lock the specified tis mutex. |
| tis_mutex_unlock() | Unlocks the specified tis mutex. |
| tis_unlock_global() | Unlocks the DECthreads global mutex. |
| Condition Variable Routines | |
| tis_cond_broadcast() | Wakes all threads waiting on the specified condition variable. |
| tis_cond_destroy() | Destroys the specified condition variable object. |
| tis_cond_init() | Initializes a condition variable object. |
| tis_cond_signal() | Wakes at least one thread that is waiting on the specified condition variable. |
| tis_cond_wait() | Causes the calling thread to wait for the specified condition variable to be signaled or broadcasted. |
| Read-Write Lock Routines | |
| tis_read_lock() | Acquires the specified read-write lock for read access. |
| tis_read_trylock() | Attempts to acquire the specified read-write lock for read access; returns immediately if already locked. |
| tis_read_unlock() | Unlocks the specified read-write lock already acquired for read access. |
| tis_rwlock_destroy() | Destroys the specified read-write lock object. |
| tis_rwlock_init() | Initializes the specified read-write lock object. |
| tis_write_lock() | Acquires the specified read-write lock for write access. |
| tis_write_trylock() | Attempts to acquire the specified read-write lock for write access; returns immediately if already locked. |
| tis_write_unlock() | Unlocks the specified read-write lock already acquired for write access. |
Previous versions of DECthreads offered interfaces that under this
DECthreads version are considered to be either undocumented but
supported, or obsolete.
1.6.3.1 Undocumented But Supported cma Interface
This version of DECthreads supports the DIGITAL-proprietary CMA (or cma) interface. The cma interface reports errors by raising exceptions. This interface is layered on top of the DECthreads pthread interface. This interface is usually available only on DIGITAL platforms.
DIGITAL will continue to support applications developed using the DECthreads cma interface. Binary compatibility will be supported indefinitely. Nonetheless, we recommend that, as soon as possible, you migrate any cma code in your existing applications to the latest DECthreads pthread interface, to take advantage of its POSIX.1c standard features, portability, and future enhancements.
Routines of the cma interface are not documented in
this guide, but are documented for previous DECthreads versions. In
this guide see Appendix E for information to help you migrate your
cma-based programs and applications to the latest
DECthreads pthread interface.
1.6.3.2 Obsolete d4 Interfaces
Note
An obsolete interface will be retired in a future DECthreads release. After retirement, that interface will no longer be enhanced or supported.
For backward compatibility only, this version of DECthreads retains full binary support for the obsolete d4 interfaces. These interfaces are implementations of the IEEE POSIX 1003.4a/Draft 4 document, and are also known as "DCE threads".
These interfaces include both a "standard" interface that reports errors by setting errno and returning a value of -1, and an "exception-returning" interface that, like the cma interface, reports errors by raising exceptions.
The DECthreads d4 interfaces are obsolete and DIGITAL plans to retire them (that is, will not be provided) in the next release of DECthreads. Thus, we recommend that you migrate any d4 code in your existing applications to the latest DECthreads pthread interface, to take advantage of its POSIX.1c standard features, portability, and future enhancements.
Routines of the d4 interfaces are not documented in this guide, but are documented for previous DECthreads versions. In this guide see Appendix F for information to help you migrate your d4-based programs and applications to the latest DECthreads pthread interface.
This chapter describes operations that act upon the objects supported
in the DECthreads pthread interface.
2.1 Threads, Mutexes, and Condition Variables
A multithreaded program typically manipulates three kinds of objects:
Before creating a thread object, mutex, or condition variable, your program can create and initialize an attributes object, which specifies the particular features of that thread, mutex, or condition variable. There are distinct kinds of attributes objects for threads, mutexes, and condition variables.