pthread, pthread_intro - Introduction to POSIX Threads
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 Readwrite
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 [Toc] [Back]
Declares fork handler routines to be called. Creates a
thread object and thread. Marks a thread object for deletion
when its thread terminates. Compares one thread
identifier to another. Terminates the calling thread.
Causes the calling thread to wait for the termination of
another thread and to detach it. Delivers a signal to a
specified thread. Calls an initialization routine to be
executed only once. Obtains the identifier of the calling
thread. Examines or changes the calling thread's signal
mask.
Thread Attributes Object Routines [Toc] [Back]
Destroys a thread attributes object. Obtains the detachstate
attribute of the specified thread attributes object.
Obtains the guardsize attribute of the specified thread
attributes object. (Supersedes pthread_attr_getguardsize_np.)
Obtains the inherit scheduling attribute of the
specified thread attributes object. Obtains the scheduling
parameters for an attribute of the specified thread
attributes object. Obtains the scheduling policy
attribute of the specified thread attributes object.
Obtains the contention scope attribute of the specified
thread attributes object. Obtains the stackaddr attribute
of the specified thread attributes object. (See also
pthread_attr_getstackaddr_np.) Obtains the stacksize
attribute of the specified thread attributes object. Initializes
a thread attributes object. Changes the detachstate
attribute of the specified thread attributes object.
Changes the guardsize attribute of the specified thread
attributes object. (Supersedes pthread_attr_setguardsize_np.)
Changes the inherit scheduling attribute of the
specified thread attributes object. Changes the values of
the parameters associated with the scheduling policy
attribute of the specified thread attributes object.
Changes the scheduling policy attribute of the specified
thread attributes object. Changes the contention scope
attribute of the specified thread attributes object.
Changes the stackaddr attribute of the specified thread
attributes object. (See also pthread_attr_setstackaddr_np.)
Changes the stacksize attribute of the specified
thread attributes object.
Thread Cancelation Routines [Toc] [Back]
Requests that a thread terminate its execution. Removes a
cleanup handler routine from the calling thread's cleanup
stack and optionally executes it. Establishes a cleanup
handler routine to be executed when the calling thread
exits or is canceled. Sets the calling thread's cancelability
state. Sets the calling thread's cancelability
type. Requests delivery of any pending cancellation
requests to the calling thread.
Thread Priority, Concurrency, and Scheduling Routines
Obtains the current concurrency level hint parameter for
the calling thread's process. Obtains the current
scheduling policy and scheduling parameters of a thread.
Changes the current concurrency level hint for the calling
thread's process. Changes the current scheduling policy
and scheduling parameters of a thread.
Thread-Specific Data Routines [Toc] [Back]
Obtains the thread-specific data associated with the specified
key. Generates a unique thread-specific data key.
Deletes a thread-specific data key. Sets the thread-specific
data value associated with the specified key for the
calling thread.
Mutex Routines [Toc] [Back]
Destroys a mutex object. Initializes a mutex object with
attributes in the specified mutex attributes object.
Locks an unlocked mutex; if already locked, the caller
waits for the mutex to become available. Attempts to lock
a mutex; returns immediately if mutex is already locked.
Unlocks a locked mutex.
Mutex Attributes Object Routines [Toc] [Back]
Initializes a mutex attributes object. Destroys a mutex
attributes object. Obtains the process-shared attribute
of the specified mutex attributes object. Obtains the
mutex type attribute of the specified mutex attributes
object. (Supersedes pthread_mutexattr_gettype_np.)
Changes the process-shared attribute of the specified
mutex attributes object. Changes the mutex type attribute
of the specified mutex attributes object. (Supersedes
pthread_mutexattr_settype_np.)
Condition Variable Routines [Toc] [Back]
Wakes all threads waiting on a condition variable.
Destroys a condition variable object. Initializes a condition
variable object. Wakes at least one thread that is
waiting on a condition variable. Causes a thread to wait
for a specified period of time for a condition variable to
be signaled or broadcast. Causes a thread to wait for a
condition variable to be signaled or broadcast.
Condition Variable Attributes Object Routines [Toc] [Back]
Destroys a condition variable attributes object. Obtains
the process-shared attribute of the specified condition
variable attributes object. Initializes a condition variable
attributes object. Changes the process-shared
attribute of the specified condition variable attributes
object.
Read-Write Lock Routines [Toc] [Back]
Destroys a read-write lock object. Initializes a readwrite
lock object. Acquires a read-write lock for read
access, after waiting if necessary. Attempts to acquire,
without waiting, a read-write lock for read access.
Attempts to acquire, without waiting, a read-write lock
for write access. Releases one acquisition by the calling
thread of a read-write lock for read access or write
access. Acquires a read-write lock for write access,
after waiting if necessary.
Read-Write Lock Attributes Object Routines [Toc] [Back]
Destroys a read-write lock attributes object. Obtains the
process-shared attribute of the specified read-write lock
attributes object. Initializes a read-write lock
attributes object. Changes the process-shared attribute
of the specified read-write lock attributes object.
Non-Portable Extensions: Thread Execution Routines
Causes a thread to delay execution. Obtains a value representing
a desired expiration time. Obtains the object
name of the specified thread object. Obtains a thread's
sequence number. Changes the object name of the specified
thread object.
Non-Portable Extensions: Thread Attributes Object Routines
Obtains the object name attribute of the specified thread
attributes object. Obtains the processor subset attribute
of the specified thread attributes object. Obtains the
stackaddr attribute of the specified thread attributes
object as low address and size. (See also
pthread_attr_getstackaddr.) Changes the object name
attribute of the specified thread attributes object.
Changes the processor subset attribute of the specified
thread attributes object. 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
Obtains the object name of a thread-specific data key
object. Changes the object name of a thread-specific data
key object.
Non-Portable Extensions: DECthreads Global Mutex Routines
Locks the DECthreads global mutex if it is unlocked.
Unlocks the DECthreads global mutex if it is locked.
Non-Portable Extensions: Mutex Routines
Obtains the object name of a mutex object. Changes the
object name of a mutex object.
Non-Portable Extensions: Condition Variable Routines
Obtains the object name of a condition variable object.
Changes the object name of a condition variable object.
Wakes one thread that is waiting on a condition variable
(called from interrupt level only). Wakes one thread that
is waiting on the specified condition variable (called
from interrupt level only).
Non-Portable Extensions: Read-Write Lock Routines
Obtains the object name of a read-write lock object.
Changes the object name of a read-write lock object.
Non-Portable Extensions: Processor Subset Object Routines
Stores the combined CPU resource descriptions from two
processor subset objects into a third. Destroys a processor
subset object. Determines whether the CPU resource
descriptions of two processor subset objects are equivalent.
Obtains CPU resource information in a thread object
and stores it in the specified processor subset object.
Initializes a processor subset object based on a processor
subset attributes object. Returns the number of processors
described in the specified processor subset object.
Stores the CPU resource descriptions from a processor subset
object into a thread object. Sets the contents of two
processor subset objects by splitting the contents of a
third.
Non-Portable Extensions: DECthreads Exception Object Routines
Obtains a system-defined error status from a DECthreads
status exception object. Determines whether two DECthreads
exception objects are identical. Produces a message
that reports what a specified DECthreads status
exception object represents. Imports a system-defined
error status into a DECthreads address exception object.
Non-Portable Extensions: Thread Priority, Concurrency, and
Scheduling Routines
Notifies the scheduler that the current thread is willing
to release its processor to other threads of the same or
higher priority.
pthread(3)
[ Back ] |
