NAME

pthread, pthread_intro − Introduction to POSIX Threads (Pthreads)

DESCRIPTION

DECthreads, DIGITAL’s multithreading run-time library, provides a set of interfaces for building multithreaded programs. One of these interfaces provides routines (with the prefix pthread_) that implement the IEEE Std 1003.1c-1995, POSIX System Application Program Interface, also known as POSIX Standard 1003.1c or POSIX.1c.  Note that POSIX Standard 1003.1c now supersedes the POSIX draft standard 1003.4a. 

A thread is a single, sequential flow of control within a program.  Within a single thread, there is a single point of execution.  Most traditional programs consist of a single thread. 

Using DECthreads, a programmer can create more than one threads within a program.  Threads execute concurrently, and, within a multithreaded program, there are at any time multiple points of execution.  The threads in a given process execute within (and share) a single address space.  Therefore, threads read and write the same memory locations.  Synchronization elements such as mutexes and condition variables ensure that the shared memory is accessed correctly.  DECthreads provides routines that allow you to create and use these synchronization elements.  Mutexes and condition variables are discussed in the Guide to DECthreads. 

Users of previous versions of DECthreads should be aware that applications consistent with the P1003.4a/D4 interface require significant modifications to be upgraded to the DECthreads pthread (POSIX.1c) interface.  See the discussion in the Guide to DECthreads. 

Routine names ending with the _np suffix denote that the routine is "not portable."  That is, such a routine might not be available in other vendor implementations of POSIX 1003.1c. 

Compile a multithreaded application using shared versions of libmach and libpthread as follows:

cc -o myprog myprog.c -pthread

If you use a compiler front-end or other (not C) language environment that does not support the -pthread compilation switch, you must use the -D_REENTRANT compilation switch. 

When linking your multithreaded application, include these switches:

-lpthread -lexc

Each C module that utilizes DECthreads exceptions must include the pthread_exception.h header file. The Guide to DECthreads describes the use of DECthreads exceptions. 

Note that previous versions of DECthreads provided a DECthreads-specific debugging interface.  However, for this version and future versions of DECthreads, we recommend the use of the DIGITAL UNIX Ladebug debugger for debugging DECthreads-based multithreaded applications. 

The Guide to DECthreads describes important considerations for threaded application development, particularly for the DIGITAL UNIX operating system. 

The pthread interface routines are 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 attribute object routines

DECthreads also provides routines that implement nonportable extensions to the POSIX 1003.1c standard.  These routines are grouped into these functional categories:

       •Thread execution routines

       •Thread attributes routines

       •DECthreads global mutex routines

       •Mutex attributes routines

       •Condition variable routines

       •DECthreads exception object routines

General Threads Routines

pthread_atforkDeclares fork handler routines to be called. 

pthread_createCreates a thread object and thread. 

pthread_detachMarks a thread object for deletion. 

pthread_equalCompares one thread identifier to another thread identifier. 

pthread_exitTerminates the calling thread. 

pthread_joinCauses the calling thread to wait for the termination of a specified thread and detach it. 

pthread_killDelivers a signal to a specified thread. 

pthread_onceCalls an initialization routine to be executed only once. 

pthread_selfObtains the identifier of the current thread. 

pthread_sigmaskExamines or changes the calling thread’s signal mask. 

Thread Attributes Object Routines

pthread_attr_destroyDestroys a thread attributes object. 

pthread_attr_getdetachstate
Obtains the detachstate attribute from the specified thread attributes object.

pthread_attr_getguardsizeObtains 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_getscopeObtains 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_getstacksizeObtains the stacksize attribute of the specified thread attributes object. 

pthread_attr_initInitializes a thread attributes object. 

pthread_attr_setdetachstate
Changes the detachstate attribute in the specified thread attributes object.

pthread_attr_setguardsizeChanges 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_setstackaddrChanges the stackaddr attribute in the specified thread attributes object. 

pthread_attr_setstacksizeChanges the stacksize attribute in the specified thread attributes object. 

Thread Cancelation Routines

pthread_cancelAllows a thread to request that it, or another thread, terminate execution. 

pthread_cleanup_popRemoves a cleanup handler routine from the top of the cleanup stack and optionally executes it. 

pthread_cleanup_pushEstablishes a cleanup handler routine to be executed when the thread exits or is canceled. 

pthread_setcancelstateSets the current thread’s cancelability state. 

pthread_setcanceltypeSets the current thread’s cancelability type. 

pthread_testcancelRequests delivery of any pending cancelation request to the current thread. 

Thread Priority, Concurrency, and Scheduling Routines

pthread_getconcurrencyObtains the current concurrency level parameter for the process. 

pthread_getschedparamObtains the current scheduling policy and scheduling parameters of a thread. 

pthread_getsequence_npObtains a thread sequence number. 

pthread_setconcurrencyChanges the current concurrency level parameter for the process. 

pthread_setschedparamChanges the current scheduling policy and scheduling parameters of a thread. 

Thread-Specific Data Routines

pthread_getspecificObtains the thread-specific data associated with the specified key. 

pthread_key_createGenerates a unique thread-specific data key. 

pthread_setspecificSets the thread-specific data value associated with the specified key for the current thread. 

pthread_key_deleteDeletes a thread-specific data key. 

Mutex Routines

pthread_mutex_destroyDestroys a mutex. 

pthread_mutex_initInitializes a mutex with attributes specified by the attributes argument. 

pthread_mutex_lockLocks an unlocked mutex; if locked, the caller waits for the mutex to become available. 

pthread_mutex_trylockAttempts to lock a mutex; returns immediately if mutex is already locked. 

pthread_mutex_unlockUnlocks a locked mutex. 

Mutex Attributes Object Routines

pthread_mutexattr_initInitializes 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_broadcastWakes all threads waiting on a condition variable. 

pthread_cond_destroyDestroys a condition variable. 

pthread_cond_initInitializes a condition variable. 

pthread_cond_signalWakes at least one thread that is waiting on a condition variable. 

pthread_cond_timedwaitCauses a thread to wait for a specified period of time for a condition variable to be signaled or broadcasted. 

pthread_cond_waitCauses a thread to wait for a condition variable to be signaled or broadcasted. 

Condition Variable Attributes Object Routines

pthread_condattr_destroyDestroys a condition variable attributes object. 

pthread_condattr_initInitializes a condition variable attributes object. 

Non-Portable Extensions: Thread Execution Routines

pthread_delay_npCauses a thread to delay execution. 

pthread_get_expiration_np
Obtains a value representing a desired expiration time.

pthread_getsequence_npObtains the thread sequence number. 

Non-Portable Extensions: Thread Attributes Routines

pthread_attr_getguardsize_np
Obtains the guardsize attribute of the specified thread attributes object.

pthread_attr_setguardsize_np
Changes the guardsize attribute of the specified thread attributes object.

Non-Portable Extensions: DECthreads Global Mutex Routines

pthread_lock_global_npLocks the DECthreads global mutex if it is unlocked. 

pthread_unlock_global_np
Unlocks the DECthreads lobal mutex if it is locked.

Non-Portable Extensions: Mutex Attributes Routines

pthread_mutexattr_gettype_np
Obtains the mutex type attribute of a mutex attributes object.

pthread_mutexattr_settype_np
Changes the mutex type attribute of a mutex attributes object.

Non-Portable Extensions: Condition Variable Routines

pthread_cond_signal_int_np
Wakes one thread that is waiting on a condition variable (called from interrupt level only).

Non-Portable Extensions: DECthreads Exception Object Routines

pthread_exc_get_status_np
Obtains a system-defined error status from a DECthreads status exception object.

pthread_exc_matches_npDetermines whether two DECthreads exception objects are identical. 

pthread_exc_report_npProduces a message that reports what a specified DECthreads status exception object represents. 

pthread_exc_set_status_np
Imports a system-defined error status into a DECthreads address exception object.