 |
Index for
Section 3 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
pthread(3)
NAME
pthread, pthread_intro - Introduction to POSIX Threads
DESCRIPTION
DECthreads, a multithreading run-time library, provides a set of interfaces
for building multithreaded programs. The POSIX threads interface provides
routines that implement the IEEE Std 1003.1c-1995, POSIX System Application
Program Interface, also known as POSIX Standard 1003.1c or POSIX.1c.
This version of DECthreads also includes additional routines specified in
the document X/Open CAE Specification, System Interfaces and Headers, Issue
5 published by the Open Group. The additional routines support creating and
operating on read-write locks and defining mutexes, condition variables,
and read-write locks as shareable across processes, via those objects'
"pshared" attribute.
Note that POSIX Standard 1003.1c now supersedes the POSIX draft standard
1003.4a. Users of previous versions of DECthreads should be aware that
applications based on the POSIX draft standard 1003.4a/D4 interface (also
known as the "d4" interface or "DCE threads") require significant
modifications to be upgraded to the POSIX threads interface. See the
discussion in the Guide to DECthreads.
The Guide to DECthreads describes important considerations for threaded
application development, particularly for the Tru64 UNIX operating system.
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 the DECthreads POSIX threads interface, a programmer can create more
than one thread 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 objects such as mutexes, condition variables,
and read-write locks ensure that data objects shared among threads are
accessed correctly. DECthreads provides routines that allow you to create
and use these synchronization objects. Mutexes, condition variables, and
read-write locks are discussed in the Guide to DECthreads.
DECthreads POSIX threads interface routines whose names have the _np suffix
are not portable. That is, such a routine might operate differently, or
might not be available, in other vendor implementations of POSIX Standard
1003.1c.
For users of the Compaq C and C++ compilers, compile a multithreaded
application as follows:
cc -c myprog.c -pthread
For users of C and C++ compilers without support for the -pthread switch,
you must ensure that the C preprocessor symbol _REENTRANT is defined before
including any system header file. One way to accomplish this is to compile
the application as follows:
cc -c myprog.c -D_REENTRANT
For users of the Compaq C and C++ compilers, when linking your
multithreaded application that use DECthreads, include only the -pthread
switch in the linker command line. Note that this switch also directs the
linker to search for thread-reentrant variants (named with the "_r" suffix)
of any libraries it searches.
For users of other language environments or C and C++ compilers that do not
support the -pthread linker switch, include these switches at the end of
the linker command line:
ld -o myprog myprog.o -lpthread -lexc -lc crt0.o
or
gcc -o myprog myprog.o -lpthread -lexc
In this case, the -lpthread and -lexc switches direct the linker explicitly
to use the DECthreads run-time and exception-handling libraries. These
switches must immediately precede the -lc switch (if specified), which
directs the linker to use the libc run-time library. If your application
also requires specific thread-reentrant variants of libraries (such as the
C run-time libraries), your linker command line must explicitly identify
them or a search path for them.
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, you must use the Ladebug debugger (or other thread-aware
debugger, such as TotalView) for debugging DECthreads-based multithreaded
applications.
You can also use the Visual Threads tool for troubleshooting and debugging
a multithreaded application. Visual Threads is part of the Developer's
Toolkit product.
DECthreads POSIX threads interface routines are grouped in the following
functional categories:
· General threads routines
· Thread attributes object routines
· Thread cancellation 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
Other DECthreads Pthread routines implement nonportable extensions to POSIX
Standard 1003.1c. These routines are grouped into these functional
categories:
· Thread execution routines
· Thread attributes object routines
· Thread-specific data routines
· DECthreads global mutex routines
· Mutex routines
· Mutex attributes object routines
· Condition variable routines
· Read-write lock routines
· Processor subset object routines
· DECthreads exception object routines
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 when its thread terminates.
pthread_equal
Compares one thread identifier to another.
pthread_exit
Terminates the calling thread.
pthread_join
Causes the calling thread to wait for the termination of another thread
and to 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 of the specified thread attributes
object.
pthread_attr_getguardsize
Obtains the guardsize attribute of the specified thread attributes
object. (Supersedes pthread_attr_getguardsize_np.)
pthread_attr_getinheritsched
Obtains the inherit scheduling attribute of 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. (See also pthread_attr_getstackaddr_np.)
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 of the specified thread attributes
object.
pthread_attr_setguardsize
Changes the guardsize attribute of the specified thread attributes
object. (Supersedes pthread_attr_setguardsize_np.)
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 of the specified thread attributes
object. (See also pthread_attr_setstackaddr_np.)
pthread_attr_setstacksize
Changes the stacksize attribute of the specified thread attributes
object.
Thread Cancelation Routines
pthread_cancel
Requests that a thread terminate its execution.
pthread_cleanup_pop
Removes a cleanup handler routine from the calling thread's cleanup
stack and optionally executes it.
pthread_cleanup_push
Establishes a cleanup handler routine to be executed when the calling
thread exits or is canceled.
pthread_setcancelstate
Sets the calling thread's cancelability state.
pthread_setcanceltype
Sets the calling thread's cancelability type.
pthread_testcancel
Requests delivery of any pending cancellation requests to the calling
thread.
Thread Priority, Concurrency, and Scheduling Routines
pthread_getconcurrency
Obtains the current concurrency level hint parameter for the calling
thread's process.
pthread_getschedparam
Obtains the current scheduling policy and scheduling parameters of a
thread.
pthread_setconcurrency
Changes the current concurrency level hint for the calling thread's
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_key_delete
Deletes a thread-specific data key.
pthread_setspecific
Sets the thread-specific data value associated with the specified key
for the calling thread.
Mutex Routines
pthread_mutex_destroy
Destroys a mutex object.
pthread_mutex_init
Initializes a mutex object with attributes in the specified mutex
attributes object.
pthread_mutex_lock
Locks an unlocked mutex; if already 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_getpshared
Obtains the process-shared attribute of the specified mutex attributes
object.
pthread_mutexattr_gettype
Obtains the mutex type attribute of the specified mutex attributes
object. (Supersedes pthread_mutexattr_gettype_np.)
pthread_mutexattr_setpshared
Changes the process-shared attribute of the specified mutex attributes
object.
pthread_mutexattr_settype
Changes the mutex type attribute of the specified mutex attributes
object. (Supersedes pthread_mutexattr_settype_np.)
Condition Variable Routines
pthread_cond_broadcast
Wakes all threads waiting on a condition variable.
pthread_cond_destroy
Destroys a condition variable object.
pthread_cond_init
Initializes a condition variable object.
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 specified period of time for a condition
variable to be signaled or broadcast.
pthread_cond_wait
Causes a thread to wait for a condition variable to be signaled or
broadcast.
Condition Variable Attributes Object Routines
pthread_condattr_destroy
Destroys a condition variable attributes object.
pthread_condattr_getpshared
Obtains the process-shared attribute of the specified condition
variable attributes object.
pthread_condattr_init
Initializes a condition variable attributes object.
pthread_condattr_setpshared
Changes the process-shared attribute of the specified 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
Acquires a read-write lock for read access, after waiting if necessary.
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 one acquisition by the calling thread of a read-write lock for
read access or write access.
pthread_rwlock_wrlock
Acquires a read-write lock for write access, after waiting if
necessary.
Read-Write Lock Attributes Object Routines
pthread_rwlockattr_destroy
Destroys a read-write lock attributes object.
pthread_rwlockattr_getpshared
Obtains the process-shared attribute of the specified read-write lock
attributes object.
pthread_rwlockattr_init
Initializes a read-write lock attributes object.
pthread_rwlockattr_setpshared
Changes the process-shared attribute of the specified read-write lock
attributes object.
Non-Portable Extensions: Thread Execution Routines
pthread_delay_np
Causes a thread to delay execution.
pthread_get_expiration_np
Obtains a value representing a desired expiration time.
pthread_getname_np
Obtains the object name of the specified thread object.
pthread_getsequence_np
Obtains a thread's sequence number.
pthread_setname_np
Changes the object name of the specified thread object.
Non-Portable Extensions: Thread Attributes Object Routines
pthread_attr_getname_np
Obtains the object name attribute of the specified thread attributes
object.
pthread_attr_getpaddock_np
Obtains the processor subset attribute of the specified thread
attributes object.
pthread_attr_getstackaddr_np
Obtains the stackaddr attribute of the specified thread attributes
object as low address and size. (See also pthread_attr_getstackaddr.)
pthread_attr_setname_np
Changes the object name attribute of the specified thread attributes
object.
pthread_attr_setpaddock_np
Changes the processor subset attribute of the specified thread
attributes object.
pthread_attr_setstackaddr_np
Changes the stackaddr attribute of the specified thread attributes
object by specifying low address and size. (See also
pthread_attr_setstackaddr.)
Non-Portable Extensions: Thread-Specific Data Routines
pthread_key_getname_np
Obtains the object name of a thread-specific data key object.
pthread_key_setname_np
Changes the object name of a thread-specific data key object.
Non-Portable Extensions: DECthreads Global Mutex Routines
pthread_lock_global_np
Locks the DECthreads global mutex if it is unlocked.
pthread_unlock_global_np
Unlocks the DECthreads global mutex if it is locked.
Non-Portable Extensions: Mutex Routines
pthread_mutex_getname_np
Obtains the object name of a mutex object.
pthread_mutex_setname_np
Changes the object name of a mutex object.
Non-Portable Extensions: Condition Variable Routines
pthread_cond_getname_np
Obtains the object name of a condition variable object.
pthread_cond_setname_np
Changes the object name of a condition variable object.
pthread_cond_signal_int_np
Wakes one thread that is waiting on a condition variable (called from
interrupt level only).
pthread_cond_sig_preempt_int_np
Wakes one thread that is waiting on the specified condition variable
(called from interrupt level only).
Non-Portable Extensions: Read-Write Lock Routines
pthread_rwlock_getname_np
Obtains the object name of a read-write lock object.
pthread_rwlock_setname_np
Changes the object name of a read-write lock object.
Non-Portable Extensions: Processor Subset Object Routines
pthread_paddock_combine_np
Stores the combined CPU resource descriptions from two processor subset
objects into a third.
pthread_paddock_destroy_np
Destroys a processor subset object.
pthread_paddock_equal_np
Determines whether the CPU resource descriptions of two processor
subset objects are equivalent.
pthread_paddock_get_np
Obtains CPU resource information in a thread object and stores it in
the specified processor subset object.
pthread_paddock_init_np
Initializes a processor subset object based on a processor subset
attributes object.
pthread_paddock_population_np
Returns the number of processors described in the specified processor
subset object.
pthread_paddock_set_np
Stores the CPU resource descriptions from a processor subset object
into a thread object.
pthread_paddock_split_np
Sets the contents of two processor subset objects by splitting the
contents of a third.
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_np
Determines whether two DECthreads exception objects are identical.
pthread_exc_report_np
Produces 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.
Non-Portable Extensions: Thread Priority, Concurrency, and Scheduling
Routines
pthread_yield_np
Notifies the scheduler that the current thread is willing to release
its processor to other threads of the same or higher priority.
|
Index for
Section 3 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|