Guide to DECthreads


Previous | Contents

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.

Table 1-1 DECthreads pthread Routines Summary
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.

Table 1-2 DECthreads tis Routines Summary
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.

1.6.3 Undocumented and Obsolete DECthreads Interfaces

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.


Chapter 2
DECthreads Objects and Operations

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:

2.2 Attributes 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.


Previous | Next | Contents