About This Manual

This guide defines the disciplines of multithreaded code, providing implementation guidelines and concepts for thread-safe and multithreaded processing environments. The guidelines are supported with reference sections describing DECthreads routines of Digital's Multithreading Run-Time Library.

DECthreads provides the POSIX 1003.1c standard (pthread) interface and a Digital proprietary (cma) interface. DECthreads also provides a tis interface to assist libraries in supporting both threaded and nonthreaded environments. The interface you select depends upon your goals and the anticipated environment for your application.

Intended Audience

This guide is intended for system and application programmers who want to create a multithreaded program using DECthreads routines.

New and Changed Features

The Guide to DECthreads is essentially a completely revised document. The primary interfaces to DECthreads in previous operating system releases were the CMA interface and the Draft 4 POSIX 1003.4a standard (subsequently renamed 1003.1c) interface. This guide reflects that the primary DECthreads interface is now the approved POSIX 1003.1c-1995 standard interface. The CMA, the Draft 4 POSIX standard interface, and the Library reference sections have been moved to Appendices. Additionally, this guide documents that the TIS interface, which supports creation of thread-safe APIs in both threaded and nonthreaded environments, is now provided.

Document Structure

This guide consists of the following:

Part I

• 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 examples demonstrating how to call DECthreads routines from a C language program.

Part II

• This part provides detailed reference information on each DECthreads POSIX 1003.1c standard (pthread) routine of the interface. The pthread routine descriptions appear in alphabetical order by routine name.

Part III

• This part provides detailed reference information on each DECthreads (Digital proprietary) tis routine. Routine descriptions appear in alphabetical order by routine name.

Part IV - Appendixes

• Appendix A discusses DECthreads issues specific to Digital UNIX systems.

• Appendix B discusses DECthreads issues and restrictions specific to OpenVMS systems.

• Appendix C discusses DECthreads issues specific to the Microsoft Win32 interfaces of Windows NT and Windows 95 systems.

• Appendix D presents information on how to debug threads.

• Appendix E provides detailed reference information on each DECthreads (Digital proprietary) cma routine. Routine descriptions appear in alphabetical order by routine name.

• Appendix F provides detailed reference information on each DECthreads (Digital proprietary) library routine. Routine descriptions appear in alphabetical order by routine name.

• Appendix G provides detailed reference information on each DECthreads POSIX 1003.4a, Draft 4 standard (pthread) routine. These routines will be retired in a future release. They are provided here as a reference to assist code migration to the final POSIX compliant routines. The pthread routine descriptions appear in alphabetical order by routine name.

Glossary

• The Glossary contains definitions of terms used in this guide, listed alphabetically.

Related Documents

See your system's documentation set for more information on that system. DECthreads is available on the following platforms:

• Digital UNIX 4.0 (formerly DEC OSF/1)

• OpenVMS Alpha Version 7.0

• OpenVMS VAX Version 7.0

Digital has changed the name of its UNIX[[R]] operating system from DEC OSF/1 to Digital UNIX. The new name reflects Digital's commitment to UNIX and its conformance to UNIX standards.

For a complete list and description of the books in the OpenVMS documentation set, see the Overview of OpenVMS Documentation.

The printed version of the Digital UNIX documentation set is color coded to help specific audiences quickly find the books that meet their needs. This color coding is reinforced with the use of an icon on the spines of books. The following list describes this convention:

Audience                                       Icon      Color Code


General users					  G    	    Blue

System and network administrators   		  S    	    Red

Programmers                			  P         Purple

Device driver writers      			  D    	    Orange

Reference page users       			  R    	    Green

Some books in the OpenVMS or Digital 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 Documentation Overview, Glossary, and Master Index provides information on all of the books in the OpenVMS or Digital UNIX documentation set.

Reader's Comments

Digital welcomes your comments on this or any other guide. You can send comments in the following ways:

• Internet electronic mail: writer@dceidl.enet.dec.com

• FAX: 603-881-0120 Attn: Run-Time Libraries Group, ZKO2-3/Q18

Please include the following information along with your comments:

• The full title of the book and the order number. (The order number is printed on the title page of this book or on its back cover.)

• The type and version of the operating system that you are using. For example, Digital UNIX Version 4.0 or OpenVMS Version 7.0.

• If known, the type of processor that is running the operating system software. For example, AlphaServer 2000.

• The section numbers and page numbers of the information on which you are commenting.

Note: Please address technical questions to your local system vendor or to the appropriate Digital technical support office. Information provided with the software media explains how to send problem reports to Digital.

How to Order Additional Documentation

Table 1 Telephone and Direct Mail Orders

Location          Call                   Fax                     Write

U.S.A.      	  DECdirect     	 800-234-2298  	    	 Digital Equipment
            	  800-DIGITAL                  			 Corporation
            	  800-344-4825                 			 P.O. Box CS2008
                                        			 Nashua, NH 03061

Canada      	  DECdirect     	 613-592-1946  	         Digital Equipment 
		  800-267-6215				         of Canada,Ltd.
                                        			 Box 13000
                                        			 100 Hertzberg Road
                                        			 Kanata, Ontario, Canada
                                        			 K2K2A6

Internal    	  DTN: 264-4446     	 603-884-3960  	         U.S. Software Supply
            	  603-884-4446

Conventions

In this guide, every use of OpenVMS means the OpenVMS operating system and every use of UNIX means the Digital UNIX operating system.

Table 2 shows the conventions used in this guide.

Table 2 Conventions

Convention         		Description

%                     		A percent sign represents the C shell system
                      		prompt.

$                     		A dollar sign represents the system prompt
                      		for the VMS DCL interface, and Bourne and Korn
                      		shells.

#                     		A number sign represents the superuser prompt.

cat(1)   		        A cross-reference to a reference page
                      		includes the appropriate section number in
                      		parentheses. For example, cat(1)
                      		indicates that you can find information on the
                      		cat command in Section 1 of the
                      		reference pages.

Ctrl/x       		        The key combination Ctrl/x indicates
                      		that you must press the key labeled Ctrl while
                      		you simultaneously press another key, for
                      		example, Ctrl/Y or Ctrl/Z.

monospaced text                 This typeface indicates the name of a command,
                      		routine, service, exception, or file. This
                      		typeface is also used in interactive examples
                      		and other screen displays. This typeface in
                      		lowercase is also used to indicate keywords,
                      		functions, files, and code statements when
                      		referencing a C language syntax.

monospaced text       	        This bolded typeface represents user input
                      		in interactive examples in the hardcopy and
                      		online versions of this guide.

 . . .                		A horizontal ellipsis in a figure or example
                      		indicates that not all of the statements are
                      		shown.

.                     		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 format descriptions, parentheses indicate
                      		that, if you choose more than one option, you
                      		must enclose the choices in parentheses.

[]                    		In format descriptions, brackets indicate
                      		that whatever is enclosed is optional; you can
                      		select none, one, or all of the choices.

{}                    		In format descriptions, braces surround a
                      		required choice of options; you must choose
                      		one of the options listed.

boldface text                   Boldface text represents the introduction
                      		of a new term. Boldface text is also used to
                      		show user input in Bookreader versions of the
                      		guide.

italic text                     Italic text represents book titles,
                      		parameters, arguments, and information that
                      		can vary in system messages (for example,
                      		Internal error number).

numbers               		Unless otherwise noted, all numbers in the
                      		text are assumed to be decimal. Nondecimal
                      		radixes-binary, octal, or hexadecimal-are
                      		explicitly indicated.

mouse                 		The term mouse refers to any pointing
                      		device, such as a mouse, a puck, or a stylus.