![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
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.
The pthread interface contains routines grouped in the following functional categories:
DECthreads 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.
Table 1-1 lists and summarizes functionally the DECthreads pthread interface routines.
| Routine | Description |
|---|---|
| General Threads Routines | |
| pthread_atfork() | Declares fork handlers 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 current thread. |
| pthread_sigmask() | Examines or changes the current 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 pthread 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_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_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_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 at the top of the cleanup stack and optionally executes it. |
| pthread_cleanup_push() | Establishes a cleanup handler to be executed when the thread exits or is canceled. |
| pthread_setcancelstate() | Sets the current thread's cancelability state. |
| pthread_setcanceltype() | Sets the current thread's cancelability type. |
| pthread_testcancel() | Requests delivery of any pending cancel to the current thread. |
| Thread Priority and Scheduling Routines | |
| pthread_getschedparam() | Obtains the current scheduling policy and scheduling parameters of a thread. |
| pthread_setschedparam() | Changes the current scheduling policy and scheduling parameters of a thread. |
| sched_yield() | Notifies the scheduler that the current thread will release its processor to other threads of the same or higher priority. |
| 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() | Sets the thread-specific data value associated with the specified key for the current 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() | Locks an unlocked mutex or returns immediately if mutex is locked. |
| pthread_mutex_unlock() | Unlocks the mutex. |
| Mutex Attributes Object Routines | |
| pthread_mutexattr_init() | Initializes a mutex attributes object. |
| pthread_mutexattr_destroy() | Destroys 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 for a condition variable to be signaled or broadcasted for a specified period of time. |
| pthread_cond_wait() | Causes a thread to wait for a condition variable to be signaled or broadcasted. |
| Condition Variable Attributes Object Routines | |
| pthread_condattr_init() | Initializes a condition variable attributes object that specifies condition variable attributes when created. |
| pthread_condattr_destroy() | Destroys a condition variable attributes object. |
| Nonportable Extensions | |
|
pthread_attr_getguardsize_np()
pthread_attr_setguardsize_np() |
Thread attribute routines |
|
pthread_delay_np()
pthread_getexpiration_np() pthread_getsequence_np() |
Thread execution routines |
|
pthread_lock_global_np()
pthread_unlock_global_np() |
Mutex routines |
|
pthread_mutexattr_gettype_np()
pthread_mutexattr_settype_np() |
Mutex attributes routines |
| pthread_cond_signal_int_np() | Condition variable routines |
|
pthread_debug()
pthread_debug_cmd() |
Debugging support routines |
In the absence of threads, tis routines impose minimal overhead on the calling program. The so-called "tis" objects created with these routines fully interoperate with the objects created by the DECthreads pthread interface routines. You cannot use tis routines to create 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 tis Routines | |
| tis_once() | Calls a one-time initialization routine that can be executed. |
| tis_raise() | Sends a signal to the thread that called tis_raise(). |
| tis_self() | Obtains the identifier of the current thread. |
| Thread Cancelation Routines | |
| tis_setcancelstate() | Sets the current thread's cancelability state. |
| tis_testcancel() | Creates a cancelation point in the current thread. |
| Key Context Routines | |
| tis_getspecific() | Obtains the data associated with the specified key. |
| tis_key_create() | Generates a unique data key. |
| tis_key_delete() | Deletes a data key. |
| tis_setspecific() | Sets the data value associated with the specified key. |
| Mutex Routines | |
| tis_lock_global() | Locks the DECthreads global mutex. |
| tis_mutex_destroy() | Destroys a tis mutex. |
| tis_mutex_init() | Initializes a tis mutex. |
| tis_mutex_lock() | Locks an unlocked tis mutex. |
| tis_mutex_trylock() | Tries to lock a tis mutex. |
| tis_mutex_unlock() | Unlocks a tis mutex. |
| tis_unlock_global() | Unlocks the DECthreads global mutex. |
| Condition Variable Routines | |
| tis_cond_broadcast() | Wakes all threads waiting on a condition variable. |
| tis_cond_destroy() | Destroys a condition variable. |
| tis_cond_init() | Initializes a condition variable. |
| tis_cond_signal() | Wakes at least one thread that is waiting on a condition variable. |
| tis_cond_wait() | Causes a thread to wait for a condition variable to be signaled or broadcasted. |
| Readers/Writer Locks | |
| tis_read_lock() | Acquires a read lock. |
| tis_read_trylock() | Acquires a read lock; returns immediately if already locked. |
| tis_read_unlock() | Unlocks a read lock. |
| tis_rwlock_destroy() | Destroys a readers/writer lock. |
| tis_rwlock_init() | Initializes a readers/writer lock. |
| tis_write_lock() | Acquires a write lock. |
| tis_write_trylock() | Acquires a write lock; returns immediately if already locked. |
| tis_write_unlock() | Unlocks a write lock. |
Previous versions of DECthreads offered interfaces that are considered to be either supported but undocumented or obsolete for this DECthreads version. Undocumented and obsolete interfaces may no longer be enhanced or supported in future versions of DECthreads.
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 not available except on Digital platforms.
Digital will continue to support applications developed using the DECthreads cma interface. Binary compatibility will be supported indefinitely. Nonetheless, it is recommended that you migrate as soon as possible any cma code in your existing applications to the latest DECthreads pthread interface to take advantage of its portability, new features, 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.
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.
These interfaces include both a "standard" interface that reports errors by setting errno and returning a value of -1, and a "exception-returning" interface that, like the cma interface, reports errors by raising exceptions.
The DECthreads d4 interfaces are obsolete and will be retired (that is, will not be provided) in a future version of DECthreads. Thus, it is recommended that you migrate any d4 code in your existing applications to the latest DECthreads pthread interface to take advantage of its portability, new features, 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.
A multithreaded program typically manipulates three kinds of objects:
Before creating a thread object, mutex, or condition variable, your program creates and initializes 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.
When your program creates a thread object, mutex, or condition variable, it can accept the default attributes for that object or specify an existing attributes object that contains particular attribute values. For a thread object, you can change some of its attributes after execution of the corresponding thread has begun---for example, you can change the thread's priority.
To create an attributes object, you can use one of the following routines, depending on the type of object to which the attributes apply:
These routines create an attributes object containing default values for the individual attributes. To modify any attribute values in an attributes object, use one of the "attr_set" routines, such as pthread_attr_setinheritsched(), described in following sections.
Creating an attributes object (or changing the values in an attributes object) does not affect the attributes of existing thread objects, mutexes, and condition variables.
To destroy an attributes object, use one of the following routines:
Deleting an attributes object does not affect the attributes of objects previously created with that attributes object.
The following sections describe these operations on threads:
Operations on threads take place with respect to a thread object. A thread object is a data structure allocated by your program, but maintained by DECthreads, that represents the attribute information and DECthreads state information about a thread.
Creating a thread means directing DECthreads to create a thread object and to assign a unique thread identifier to the thread object. The thread object encapsulates attribute information about the thread and DECthreads' own state information about the thread. After a thread has been created, DECthreads has all the information it requires to start a distinct sequence of execution with this process.
Starting a thread means DECthreads hands the addresses of a start routine and its arguments to the operating system for execution on some CPU within this system.
Your program creates a thread using the pthread_create() routine. This routine creates a thread object based on the settings of a specified thread attributes object, which your program must have previously created and initialized. Otherwise, without specifying a thread attributes object, you can create a new thread that has DECthreads default attributes.
By default, DECthreads creates a thread in the ready state and prepares the thread to begin executing its start routine, the function passed to the pthread_create() routine. Depending on the presence of other threads and their scheduling and priority attributes, the new thread might start executing immediately. The new thread can also preempt its creator, depending on the two threads' respective scheduling and priority attributes. The caller of pthread_create() can synchronize with the new thread using the pthread_join() routine or using any mutually agreed upon mutexes or condition variables.
For the duration of the new thread's existence, DECthreads maintains and manages the thread object and other thread state overhead. A thread exists until it is both terminated and detached. (See Section 2.3.3 and Section 2.3.4 for more information about terminating and detaching threads.)
DECthreads assigns each new thread a thread identifier, which DECthreads writes into the address specified as the pthread_create() routine's thread argument. DECthreads writes the new thread's thread identifier before the new thread executes.
By default, the new thread's scheduling policy and priority are inherited from the creating thread; that is, by default the pthread_create() routine ignores the scheduling policy and priority set in the specified thread attributes object. To create a thread subject to the scheduling policy and priority set in the specified thread attributes object, your program must first disable the inherit scheduling attribute by calling pthread_attr_setinheritsched() before calling pthread_create().
You can create a thread that is detached. To do so, create a thread using a thread attributes object whose detachstate attribute has been set, using the pthread_attr_setdetach() routine, to PTHREAD_CREATE_DETACHED. This is useful for creating a thread that your program knows will not join on any other thread. That is, when such a thread terminates, DECthreads automatically destroys the thread and its thread object.
For more detailed information about thread creation, see the reference description of the pthread_create() routine in Part 2.
When creating a thread, your program can optionally specify the attributes of the new thread using a thread attributes object. To do so, your program must:
6493P001.HTM OSSG Documentation 22-NOV-1996 13:19:56.45
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.