 |
Guide to DECthreads
Order Number:
AA--QSBPC--TE
January 1999
This guide reviews the principles of multithreaded programming, as
reflected in the IEEE POSIX 1003.1c-1995 standard, and provides
implementation guidelines and reference information for DECthreads,
Compaq's Multithreading Run-Time Library.
Revision/Update Information:
This manual supersedes the Guide to DECthreads, Version 7.1.
Software Version:
OpenVMS Alpha Version 7.2
OpenVMS VAX Version 7.2
Compaq Computer Corporation Houston, Texas
January 1999
Compaq Computer Corporation makes no representations that the use of
its products in the manner described in this publication will not
infringe on existing or future patent rights, nor do the descriptions
contained in this publication imply the granting of licenses to make,
use, or sell equipment or software in accordance with the description.
Possession, use, or copying of the software described in this
publication is authorized only pursuant to a valid written license from
Compaq or an authorized sublicensor.
Compaq conducts its business in a manner that conserves the environment
and protects the safety and health of its employees, customers, and the
community.
© Compaq Computer Corporation 1999. All rights reserved
The following are trademarks of Compaq Computer Corporation: Alpha,
AlphaServer, Bookreader, Compaq, DEC, DEC Ada, DECdirect, DECthreads,
DIGITAL, DIGITAL UNIX, Ladebug, OpenVMS, OpenVMS Cluster, ULTRIX, VAX,
VAX Ada, VAX DOCUMENT, VAX MACRO, VAXcluster, VMS, and the Compaq logo.
The following are third-party trademarks:
IEEE and POSIX are registered trademarks of the The Institute for
Electrical and Electronics Engineers, Inc.
Microsoft, MS, MS--DOS, Win32, and Windows NT are registered trademarks
and Windows 95 is a trademark of Microsoft Corporation.
Motif, OSF, OSF/1, and OSF/Motif are registered trademarks and Open
Software Foundation is a trademark of the Open Software Foundation, Inc.
UNIX is a registered trademark in the United States and other
countries, licensed exclusively through X/Open Company Ltd.
All other trademarks and registered trademarks are the property of
their respective holders.
ZK6493
The OpenVMS documentation set is available on CD-ROM.
This document was prepared using VAX DOCUMENT, Version V3.2n.
Preface
Intended Audience
This guide is for system and application programmers who use DECthreads
to create multithreaded applications or to create thread-safe code
libraries that can be called from single-threaded or multithreaded
applications.
Document Structure
This guide consists of the following:
Part 1
- Chapter 1 provides a brief overview of multithreaded programming.
- Chapter 2 discusses the concepts and techniques related to
DECthreads.
- 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 DECthreads exception package.
- Chapter 6 contains an example demonstrating how to call
DECthreads routines from a C language program.
Part 2
- This part provides detailed reference information on each
pthread interface routine. Routine descriptions appear
in alphabetical order by routine name.
Part 3
- 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 DECthreads issues and restrictions specific
to Compaq's DIGITAL UNIX systems.
- Appendix B discusses DECthreads issues and restrictions specific
to OpenVMS systems.
- Appendix C discusses DECthreads issues and restrictions specific
to the Microsoft Win32 interfaces on Windows NT systems.
- Appendix D discusses debugging issues for a multithreaded
program that uses DECthreads.
- Appendix E summarizes the differences between the Compaq
proprietary DECthreads CMA (or cma) interface and the
DECthreads pthread interface. Use this appendix to
help you migrate your programs and applications to the
pthread interface.
- Appendix F summarizes the differences between the DECthreads
POSIX 1003.4a/Draft 4 (or d4) interface and the
DECthreads pthread interface. Use this appendix to
help you migrate your programs and applications to the
pthread interface.
Glossary
- The Glossary contains definitions of terms used in this guide,
listed alphabetically.
Related Documents
For additional information on the Open Systems Software Group (OSSG)
products and services, access the following OpenVMS World Wide Web
address:
http://www.openvms.digital.com
|
Reader's Comments
Compaq welcomes your comments on this manual.
Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send
us your comments by:
Internet
|
writer@dceidl.enet.dec.com
|
Fax
|
603 884-0120, Attention: Core Technology Group, ZKO2-3/Q18
|
Mail
|
Core Technology Group, ZKO2-3/Q18
110 Spit Brook Rd.
Nashua, NH 03062-2698
|
How To Order Additional Documentation
Use the following World Wide Web address to order additional
documentation:
http://www.openvms.digital.com:81/
|
If you need help deciding which documentation best meets your needs,
call (800-282-6672).
Conventions
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.
The following conventions are used in this manual:
...
|
A horizontal ellipsis in examples indicates one of the following
possibilities:
- 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 the options in parentheses if you choose more than one.
|
[ ]
|
In command format descriptions, brackets indicate optional elements.
You can choose one, none, or all of the options. (Brackets are not
optional, however, in the syntax of a directory name in an OpenVMS file
specification or in the syntax of a substring specification in an
assignment statement.)
|
[|]
|
In command format descriptions, vertical bars separating items inside
brackets indicate that you choose one, none, or more than one of the
options.
|
{ }
|
In command format descriptions, braces indicate required elements; you
must choose one of the options listed.
|
text style
|
This text style represents the introduction of a new term or the name
of an argument, an attribute, or a reason.
In the HTML version of this document, this convention appears as
italic text.
|
italic text
|
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
|
Uppercase text indicates a command, the name of a routine, the name of
a file, or the abbreviation for a system privilege.
|
Monospace type
|
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
following line.
|
numbers
|
All numbers in text are assumed to be decimal unless otherwise noted.
Nondecimal radixes---binary, octal, or hexadecimal---are explicitly
indicated.
|
Part 1 DECthreads Overview and Programming Guidelines
Part 1 contains chapters that provide an overview and concepts of
DECthreads as well as defining programming disciplines and guidelines
for writing a multithreaded program.
Chapter 1 Introducing DECthreads for 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 DECthreads
package, in particular the pthread and
tis interfaces, and how those components support
building multithreaded applications and thread-safe libraries.
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 DECthreads library are capable of
utilizing multiprocessors, if the target platform supports parallelism
within a process. Compaq's DIGITAL UNIX platforms and OpenVMS Alpha
platforms support parallelism; the OpenVMS VAX platform does not
support parallelism.
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
and stack.
Using DECthreads, Compaq's multithreading run-time library, a
programmer can create several threads within a process. The process's
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's 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. DECthreads
provides routines that allow you to use these and other synchronization
objects. Section 2.4 describes the synchronization objects that
DECthreads 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 DECthreads thread scheduler, part of the run-time environment that
DECthreads establishes before your program begins running.
Nevertheless, your program can influence how DECthreads schedules its
threads, 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 thread-common 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:
- Waiting---The thread is not eligible to execute, because
it is synchronizing with another thread or with an external event, such
as I/O.
- Ready---The thread is eligible to be executed by a
processor.
- Running---The thread is currently being executed by a
processor.
- 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
implementation.
Figure 1-3 Thread State Transitions
Note
Building your multithreaded program must produce executable code that
is reentrant. Therefore, be sure that your compiler generates
reentrant code before you design or code your multithreaded program. By
default, Compaq's C, C++, Ada, Pascal, and BLISS compilers generate
reentrant code.
If you cannot build your program so that its executable code is
reentrant, it might be impossible to keep the program's threads from
interfering with each other. See Section 3.9.1 for more information
about thread-reentrant libraries.
In general, when using threads, be aware of language-based programming
practices that are inherently not thread safe. ("Thread
safety" is explained in Section 3.9.2.) You must address these
factors when writing multithreaded applications and thread-safe
libraries. For example, Fortran language routines typically rely
heavily upon static storage, which can prevent those routines from
being thread safe.
|
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
multithreaded programs:
- 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.
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
work on.
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
independently.
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
work crew.
When you design and code a multithreaded program, you must accommodate
or eliminate, as appropriate, each of the following issues:
-
Program complexity is the most significant issue to consider
in any multithreaded programming effort. Although using threads can
simplify the coding and designing of a program, a certain level of
expertise is required to be sure that the design of the synchronization
and interplay among threads is appropriate and correctly specified.
This level of expertise is higher than that required to design most
single-threaded programs.
-
Dependence upon other nonreentrant software means that your
multithreaded program calls a routine or library that is not equipped
to deal with threads. Given this dependence, your program must use the
DECthreads global lock to prevent conflicts with other threads that use
the same nonreentrant routine or library. Section 3.9 presents
multithreaded programming techniques for managing dependencies upon
other nonreentrant software.
-
Due to programming errors, race conditions in the program's
behavior can cause unpredictable and erroneous program behavior.
Similarly, deadlocks can cause two or more threads to be
blocked from executing indefinitely. Section 3.6.2 discusses race
conditions in more detail, and Section 3.6.3 discusses deadlocks.
-
Priority inversion prevents high-priority threads from
executing when interdependencies exist among three or more threads of
different priorities. Section 3.5.2 discusses techniques for avoiding
priority inversion.
|