Guide to the POSIX Threads Library
Guide to the POSIX Threads Library
This guide reviews the principles of multithreaded programming, as
reflected in the IEEE POSIX 1003.1-1996 standard, and provides
implementation guidelines and reference information for the Compaq
Multithreading Run-Time Library.
This manual supersedes the Guide to DECthreads, January 1999.
OpenVMS Alpha Version 7.3 OpenVMS VAX Version 7.3
Compaq Computer Corporation Houston, Texas
© 2001 Compaq Computer Corporation
Compaq, VAX, VMS, and the Compaq logo Registered in the U.S. Patent and
Tru64 and OpenVMS are trademarks of Compaq Information Technologies
Group, L.P. in the United States and other countries.
Microsoft is a trademark of Microsoft Corporation in the United States
and other countries. UNIX is a registered trademark and The Open Group
is a trademark of The Open Group in the U.S. and other countries.
All other product names mentioned herein may be trademarks of their
Confidential computer software. Valid license from Compaq required for
possession, use, or copying. Consistent with FAR 12.211 and 12.212,
Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government
under vendor's standard commercial license.
The information in this document is provided "as is" without warranty
of any kind and is subject to change without notice. The warranties for
Compaq products are set forth in the express limited warranty
statements accompanying such products. Nothing herein should be
construed as constituting an additional warranty.
The Compaq OpenVMS documentation set is available on
This guide describes the POSIX Threads Library, Compaq's Multithreading
Run-Time Library. In addition to introducing components for building
multithreaded applications and libraries to be called from either
single-threaded or multithreaded programs, this guide reviews the key
principles of multithreaded programming.
This guide also presents the concepts behind thread-safe and
multithreaded processing environments and provides guidelines for using
the library to implement them on various Compaq platforms. Finally,
this guide describes in detail each routine in the two recommended
- For building portable, multithreaded applications, Compaq provides
the pthread interface. This is an implementation of
the POSIX standard 1003.1c-1995 (part of 1003.1-1996). This interface
adds extensions specified in The Open Group's Single Unix
Specification, Version 2 (SUSV2), also known as XSH5, part of the
- For building libraries whose routines can be called in either a
single-threaded or multithreaded context, Compaq provides a proprietary
thread-independent services (or tis) interface.
The interface you select depends upon your goals and the anticipated
environment for your software.
As a complement to this guide, and for a user's guide to multithreaded
programming using the pthreads standard, we recommend the following:
Programming with POSIX Threads by David R. Butenhof, published
as part of the Addison-Wesley Professional Computing Series (ISBN
The Single UNIX Specification, Version 2, The Open Group
(ISBN 85912-181-0). Available online at
This guide is for system and application programmers who use the POSIX
Threads Library either to create multithreaded applications or to
create thread-safe code libraries that can be called from either
single-threaded or multithreaded applications.
This guide consists of the following:
- Chapter 1 provides a brief overview of multithreaded programming.
- Chapter 2 discusses the concepts and techniques related to the
POSIX Threads Library.
- Chapter 3 describes thread disciplines and coding issues you may
face when writing a multithreaded program.
- Chapter 4 addresses writing thread-safe libraries.
- Chapter 5 introduces and provides conventions for the modular use
of the POSIX Threads Library exception package.
- Chapter 6 contains example programs demonstrating how to call
library routines from a C language program.
- This part provides detailed reference information on each
pthread interface routine. Routine descriptions appear
in alphabetical order by routine name.
- This part provides detailed reference information on each
tis interface routine. Routine descriptions appear in
alphabetical order by routine name.
Part 4 - Appendixes
- Appendix A discusses POSIX Threads Library issues and
restrictions specific to Compaq Tru64 UNIX systems.
- Appendix B discusses POSIX Threads Library issues and
restrictions specific to OpenVMS systems.
- Appendix C discusses debugging issues for a multithreaded
program that uses the POSIX Threads Library.
- Appendix D summarizes the differences between the obsolete
Compaq-proprietary CMA (or cma) interface and the
Compaq pthread interface. Use this appendix to help
you migrate your programs and applications to the
- Appendix E summarizes the differences between the retired POSIX
1003.4a/Draft 4 (d4 or DCEthreads)
interface and the Compaq pthread interface. Use this
appendix to help you migrate your programs and applications to the
- The Glossary contains definitions of terms used in this guide,
See your system's documentation set for more information on that
system. This manual covers the version of the POSIX Threads Library
available on the following platforms:
- Tru64 UNIX 5.0A or higher
- OpenVMS Alpha Version 7.3
- OpenVMS VAX Version 7.3
For a complete list and description of the books in the OpenVMS
documentation set, see the OpenVMS Version 7.3 New Features and
Some books in the OpenVMS or Tru64 UNIX documentation set help meet the
needs of several audiences. For example, the information in some system
manager, system administrator, or user books is also used by
programmers. Keep this in mind when searching for information on
specific topics. The New Features Manual provides information on all of
the books in the OpenVMS or Tru64 UNIX documentation set.
For additional information on the Open Systems Software Group (OSSG)
products and services, access the Compaq World Wide Web site at the
Compaq welcomes your comments on this guide. Please send comments to
any of the following addresses:
603 881-0120, Attention: Core Technology Group, ZKO2-3/Q18
Compaq Computer Corporation
Core Technology Group, ZKO2-3/Q18
110 Spit Brook Rd.
Nashua, NH 03062-2698
VMScluster systems are now referred to as OpenVMS Cluster systems.
Unless otherwise specified, references to OpenVMS Clusters or clusters
in this document are synonymous with VMSclusters.
In this manual, every use of DECwindows and DECwindows Motif refers to
DECwindows Motif for OpenVMS software.
The following conventions are used in this manual:
A sequence such as Ctrl/
x indicates that you must hold down the key labeled Ctrl while
you press another key or a pointing device button.
A sequence such as PF1
x indicates that you must first press and release the key
labeled PF1 and then press and release another key or a pointing device
In examples, a key name enclosed in a box indicates that you press a
key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as
brackets, rather than a box.
A horizontal ellipsis in examples indicates one of the following
- Additional optional arguments in a statement have been omitted.
- The preceding item or items can be repeated one or more times.
- Additional parameters, values, or other information can be entered.
A vertical ellipsis indicates the omission of items from a code example
or command format; the items are omitted because they are not important
to the topic being discussed.
In command format descriptions, parentheses indicate that you must
enclose choices in parentheses if you specify more than one.
In command format descriptions, brackets indicate optional choices. You
can choose one or more items or no items. Do not type the brackets on
the command line. However, you must include the brackets in the syntax
for OpenVMS directory specifications and for a substring specification
in an assignment statement.
In command format descriptions, vertical bars separate choices within
brackets or braces. Within brackets, the choices are optional; within
braces, at least one choice is required. Do not type the vertical bars
on the command line.
In command format descriptions, braces indicate required choices; you
must choose one of the items listed. Do not type the braces on the
This typeface represents the introduction of a new term. It also
represents the name of an argument, an attribute, or a reason.
In the HTML version of this document, this convention appears as
Italic text indicates important information, complete titles of
manuals, or variables. Variables include information that varies in
system output (Internal error
number), in command lines (/PRODUCER=
name), and in command parameters in text (where
dd represents the predefined code for the device type).
Uppercase text indicates a command, the name of a routine, the name of
a file, or the abbreviation for a system privilege.
Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the
following elements: keywords, the names of independently compiled
external functions and files, syntax summaries, and references to
variables or identifiers introduced in an example.
A hyphen at the end of a command format description, command line, or
code line indicates that the command or statement continues on the
All numbers in text are assumed to be decimal unless otherwise noted.
Nondecimal radixes---binary, octal, or hexadecimal---are explicitly
Part 1 contains chapters that provide an overview and concepts of
the Threads Library as well as define programming disciplines and
guidelines for writing a multithreaded program.
Compaq POSIX Threads Library Overview and Programming Guidelines
Introducing Multithreaded Programming
This chapter introduces the concepts of threads and multithreaded
programming. It describes four functional models that can be a basis
for constructing multithreaded applications. The concepts and
techniques introduced here are described in more detail in Chapter 2
and in this guide's platform-specific appendixes.
This chapter's last section introduces the components of the POSIX
Threads Library package, in particular the pthread and
tis interfaces, and how those components support
building multithreaded applications and thread-safe libraries.
1.1 Advantages of Using Threads
Multithreaded programming means organizing and coding
a program so that instances of its routines, called threads, can
execute concurrently in the same process. You use threads to improve a
program's performance---that is, its throughput, computational speed,
responsiveness, or some combination.
Using threads can improve a program's performance on uniprocessor
systems by permitting the overlap of input, output, or other slow
operations with computational operations. Threads are useful in driving
slow devices such as disks, networks, terminals, and printers. A
multithreaded program can perform other useful work while waiting for
the device to produce its next event, such as the completion of a disk
transfer or the receipt of a packet from the network.
Using threads can also be advantageous when constructing an
application's user interface. Consider the typical arrangement of a
window system. Each time the user invokes an action (for example, by
clicking on a mouse button), the program can use a separate thread to
implement the action. If the user invokes multiple actions, multiple
threads can perform the actions in parallel.
Using threads is especially advantageous when building a distributed
system. These systems frequently contain a shared network server, where
the server services requests from multiple clients. Using multiple
threads allows the server to handle clients' requests in parallel,
instead of artificially serializing them or creating (at great expense)
one server process per client.
A program with multiple threads can be especially suited to run on a
multiprocessor system, where threads run concurrently on separate
processors. Threads created using the POSIX Threads Library are capable
of utilizing multiprocessors, if the target platform supports
parallelism within a process. Compaq's Tru64 UNIX platforms and OpenVMS
Alpha platforms support parallelism; the OpenVMS VAX platform does not
1.2 Overview of Threads
A thread is a single, sequential flow of control
within a process. Within each thread there is a single point of
execution. Most traditional programs execute as a process with a single
thread. Figure 1-1 and Figure 1-2 show the differences between a
single-threaded process and a multithreaded process.
Figure 1-1 Single-Threaded Process
In Figure 1-2, notice that multiple threads share heap storage,
static storage, and code but that each thread has its own register set
Using Compaq's multithreading run-time library, a programmer can create
several threads within a process. The process' threads execute
concurrently. Within a multithreaded program there are at any time
multiple points of execution.
Threads execute within (and share) a single address space; therefore, a
process' threads can read and write the same memory locations. When the
threads access the same memory locations, your program must use
synchronization elements, such as mutexes and condition variables, to
ensure that the shared memory is accessed correctly. The Threads
Library provides routines that allow you to use these and other
synchronization objects. Section 2.4 describes the synchronization
objects that the Threads Library offers as well as the operations your
program can perform on them.
Figure 1-2 Multithreaded Process
1.3 Thread Execution
You should design and code a multithreaded program with the assumption
that its threads execute simultaneously. That is, your program
cannot make assumptions about the relative start or finish times of its
threads or the sequence in which they execute. These are governed by
the thread scheduler, part of the run-time environment that the Threads
Library establishes before your program begins running. Nevertheless,
your program can influence how threads are scheduled by setting each
thread's scheduling policy and scheduling priority. ( Section 2.3.6
describes how thread scheduling works.)
Each thread has its own thread identifier, which distinguishes it from
all other threads in the process. In addition to the thread's
scheduling policy and scheduling priority, each thread is associated
with any thread-specific instances of data objects and with
thread-specific system resources to support a flow of control.
A thread changes its state over the course of its execution. A thread
is in one of the following states:
- Blocked---The thread is not eligible to execute, because
it is synchronizing with another thread or with an external event, such
- Ready---The thread is eligible to be executed by a
- Running---The thread is currently being executed by a
- Terminated---The thread has completed all of its work or
has been canceled.
Figure 1-3 shows the transitions between states for a typical thread
Figure 1-3 Thread State Transitions
1.4 Functional Models for Multithreaded Programming
The following sections describe four functional models of processing
information that are especially well suited for implementation in
- Boss/worker model
- Work crew model
- Pipelining model
- Combination of models
1.4.1 Boss/Worker Model
In a boss/worker model, one thread functions as the
"boss" because it assigns tasks for "worker"
threads to perform. Each worker performs a distinct task until it has
finished, at which point it notifies the boss that it is ready to
receive another task. Alternatively, the boss polls workers
periodically to see whether any is ready to receive another task.
A variation of the boss/worker model is the work queue model.
The boss places tasks in a queue, and workers check the queue and take
tasks to perform. When there are multiple bosses, this is often called
An example of the work queue model in an office environment is a
secretarial typing pool. The office manager boss puts documents to be
typed in a basket, and worker typists take documents from the basket to
1.4.2 Work Crew Model
In the work crew model, multiple threads work together on a
single task. The task is divided into pieces that are performed in
parallel, and each thread performs one piece.
An example of a work crew is a group of people cleaning a building.
Each person cleans certain rooms or performs certain types of work
(washing floors, polishing furniture, and so forth), and each works
In a multithreaded program that reflects the work crew model, each
thread executes a task that can be performed in parallel. Figure 1-4
shows a task performed by three threads in a work crew model.
Figure 1-4 Work Crew Model of Thread Operation
1.4.3 Pipelining Model
In the pipelining model, a task is divided into steps. The
steps must be performed in sequence to produce a single instance of the
desired result, and the work done in each step (except for the first
and last) is based on the previous step and is a prerequisite for the
work in the next step. However, the goal is to produce multiple
instances of the desired result, and the steps are designed to operate
in parallel: while one step is performed on one instance of the result,
the preceding step can be performed on the next instance of the result.
An example of the pipelining model is an automobile assembly line. Each
step or stage in the assembly line is continually busy receiving the
product of the previous stage's work, performing its assigned work, and
passing the product along to the next stage.
In a multithreaded program that reflects the pipelining model, each
thread executes a step in the task. Figure 1-5 shows a task performed
by three threads in a pipelining model.
Figure 1-5 Pipelining Model of Thread Operation
1.4.4 Combination of Functional Models
If the task that your program performs is complex, you might find it
appropriate to organize it as a combination of the functional models
previously described. For example, a program could follow the
pipelining model, but with one or more steps performed by a set of
threads that follow a work crew model. In addition, threads could be
assigned to a work crew by taking a task from a work queue and deciding
(based on the task characteristics) which threads are needed for the