Guide to DECthreads

Updated: 11 December 1998

Guide to DECthreads

Contents

Index

1.6 DECthreads Libraries and Interfaces

As a package, DECthreads is a collection of shared code libraries and C language header files that declare entry points into those libraries. This guide's platform-specific appendixes describe these libraries in more detail and list all other libraries upon which the DECthreads libraries depend.

From the programmer's view the DECthreads libraries offer interfaces. Each interface is a distinct set of routines that together provide a well-defined set of related data objects and operations.

This version of DECthreads supports two interfaces that are documented in this guide:

The pthread interface provides multithreading capability in your applications. This interface is based on the IEEE POSIX 1003.1c-1995 standard. Use this interface to build portable, multithreaded applications.
Section 1.6.1 introduces the pthread interface. Chapter 2 and Chapter 3 describe how to use the features and functionality of the pthread interface. The reference descriptions in Part 2 describe in detail each routine in the pthread interface.
The Compaq proprietary tis interface offers routines that provide thread-independent services. The routines in this interface enable your software to perform thread-safe processing that requires synchronization, but without requiring the use of threads.
Section 1.6.2 introduces the tis interface. Chapter 4 describes how to use the features and functionality of the tis interface. The reference descriptions in Part 3 describe in detail each routine in the tis interface.

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:

General threads routines
Thread attributes object routines
Thread cancelation routines
Thread priority, concurrency, and scheduling routines
Thread-specific data routines
Mutex routines
Mutex attributes object routines
Condition variable routines
Condition variable attributes object routines
Read-write lock routines
Read-write lock attributes object routines

The DECthreads pthread interface also provides routines that implement nonportable extensions to the POSIX.1c standard. These routines are grouped in these functional categories:

Thread execution routines
DECthreads global mutex routines
Mutex attributes routines
Condition variable routines
Object naming routines
DECthreads exception object routines

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_getpshared() Obtains the value of the process-shared attribute of a mutex attributes object.

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_setpshared() Changes the value of the process-shared 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_getpshared() Obtains the value of the process-shared attribute of a condition variable attributes object.

pthread_condattr_destroy() Destroys a condition variable attributes object.

pthread_condattr_init() Initializes a condition variable attributes object.

pthread_condattr_setpshared() Changes the value of the process-shared attribute of a condition variable attributes object.

Read-Write Lock Routines

pthread_rwlock_destroy() Destroys a read-write lock object.

pthread_rwlock_init() Initializes a read-write lock object.

pthread_rwlock_rdlock() Attempts to acquire, while waiting, a read-write lock for read access.

pthread_rwlock_tryrdlock() Attempts to acquire, without waiting, a read-write lock for read access.

pthread_rwlock_trywrlock() Attempts to acquire, without waiting, a read-write lock for write access.

pthread_rwlock_unlock() Releases an acquired read-write lock.

pthread_rwlock_wrlock() Attempts to acquire, while waiting, a read-write lock for write access.

Read-Write Lock Attributes Object Routines

pthread_rwlockattr_destroy() Destroys a read-write lock attributes object.

pthread_rwlockattr_getpshared() Obtains value of process-shared attribute of a read-write lock attributes object.

pthread_rwlockattr_init() Initializes a read-write lock attributes object.

pthread_rwlockattr_setpshared() Changes value of process-shared attribute of a read-write lock 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 object routines

pthread_lock_global_np()
pthread_unlock_global_np() DECthreads global mutex routines

pthread_mutexattr_gettype_np()
pthread_mutexattr_settype_np() Mutex attributes object 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_rwlock_getname_np()
pthread_rwlock_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 (macros)

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.

**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_getpshared()	Obtains the value of the process-shared attribute of a mutex attributes object.
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_setpshared()	Changes the value of the process-shared 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_getpshared()	Obtains the value of the process-shared attribute of a condition variable attributes object.
pthread_condattr_destroy()	Destroys a condition variable attributes object.
pthread_condattr_init()	Initializes a condition variable attributes object.
pthread_condattr_setpshared()	Changes the value of the process-shared attribute of a condition variable attributes object.
Read-Write Lock Routines
pthread_rwlock_destroy()	Destroys a read-write lock object.
pthread_rwlock_init()	Initializes a read-write lock object.
pthread_rwlock_rdlock()	Attempts to acquire, while waiting, a read-write lock for read access.
pthread_rwlock_tryrdlock()	Attempts to acquire, without waiting, a read-write lock for read access.
pthread_rwlock_trywrlock()	Attempts to acquire, without waiting, a read-write lock for write access.
pthread_rwlock_unlock()	Releases an acquired read-write lock.
pthread_rwlock_wrlock()	Attempts to acquire, while waiting, a read-write lock for write access.
Read-Write Lock Attributes Object Routines
pthread_rwlockattr_destroy()	Destroys a read-write lock attributes object.
pthread_rwlockattr_getpshared()	Obtains value of process-shared attribute of a read-write lock attributes object.
pthread_rwlockattr_init()	Initializes a read-write lock attributes object.
pthread_rwlockattr_setpshared()	Changes value of process-shared attribute of a read-write lock 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 object routines

pthread_lock_global_np() pthread_unlock_global_np()	DECthreads global mutex routines

pthread_mutexattr_gettype_np() pthread_mutexattr_settype_np()	Mutex attributes object 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_rwlock_getname_np() pthread_rwlock_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 (macros)
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:

Reported by the POSIX.1c _POSIX_THREAD_PRIO_PROTECT macro:
- pthread_mutex_getprioceiling()
- pthread_mutex_setprioceiling()
- pthread_mutexattr_getprioceiling()
- pthread_mutexattr_setprioceiling()
Reported by the POSIX.1c _POSIX_THREAD_PRIO_PROTECT and
_POSIX_THREAD_PRIO_INHERIT macros:
- pthread_mutexattr_getprotocol()
- pthread_mutexattr_setprotocol()
(Not supported for OpenVMS systems) Reported by the POSIX.1c _POSIX_THREAD_PROCESS_SHARED macro:
- pthread_condattr_getpshared()
- pthread_condattr_setpshared()
- pthread_mutexattr_getpshared()
- pthread_mutexattr_setpshared()
- pthread_rwlockattr_getpshared()
- pthread_rwlockattr_setpshared()

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.

Contents

Index

Legal

 
6101PRO_001.HTML