Guide to DECthreads

2 Thread Concepts and Operations

2.1 Thread Operations

2.1.1 Starting a Thread

2.1.2 Terminating a Thread

2.1.3 Termination

2.1.4 Waiting for a Thread to Terminate

2.1.5 Deleting a Thread

2.2 Attributes Objects

2.2.1 Creating an Attributes Object

2.2.2 Deleting an Attributes Object

2.2.3 Thread Attributes

2.2.3.1 Inherit Scheduling Attribute

2.2.3.2 Scheduling Policy Attribute

2.2.3.3 Scheduling Parameters Attribute

2.2.3.4 Stacksize Attribute

2.2.3.5 Guardsize Attribute

2.2.4 Mutex Attributes

2.2.4.1 Mutex Type Attribute

2.2.5 Condition Variable Attributes

2.3 Synchronization Objects

2.3.1 Mutexes

2.3.1.1 Normal Mutex

2.3.1.2 Recursive Mutex

2.3.1.3 Errorcheck Mutex

2.3.1.4 Mutex Operations

2.3.2 Condition Variables

2.3.3 Other Synchronization Methods

2.4 One-Time Initialization

2.5 Thread-Specific Data

2.6 Thread Cancellation

2.7 Thread Scheduling

3 Programming with Threads

3.1 Design for Asynchronous Execution

3.1.1 Memory Synchronization

3.2 Threads and Libraries

3.2.1 Thread Reentrant

3.2.2 Thread-Safe

3.2.3 Unsafe

3.2.3.1 DECthreads Global Lock

3.3 General Threaded Programming Issues

3.3.1 Shared Memory

3.3.1.1 Static

3.3.1.2 Stack

3.3.1.3 Heap

3.4 Stack Management

3.4.1 Stack Overflow

3.4.2 Sizing the Stack

3.5 Scheduling

3.5.1 Priority Inversion

3.6 Using Synchronization Objects

3.6.1 Mutex or Condition Variable

3.6.2 Race Conditions

3.6.3 Deadlocks

3.6.4 Signaling a Condition Variable

3.7 DECthreads Error Reporting

3.8 Multiple Threads Libraries Use Not Supported

4 Writing Thread-Safe Libraries

4.1 Mutexes

4.2 Condition Variables

4.3 Thread-Specific Data

4.4 Readers/Writer Locks

5 Using the DECthreads Exception Package

5.1 Overview of Exceptions

5.1.1 Types of Exceptions

5.1.2 Terminating Exception Semantics

5.2 Exception Operations

5.2.1 Declaring and Initializing an Exception Object

5.2.2 Raising an Exception

5.2.3 Defining a Code Region to Catch Exceptions

5.2.4 Catching a Particular Exception

5.2.5 Catching All Exceptions

5.2.6 Reraising the Current Exception

5.2.7 Defining Epilogue Actions for a Block

5.2.8 Determining the Current Exception

5.2.9 Importing a System-Defined Error Status into the Program as an Exception

5.2.10 Exporting a System-Defined Error Status

5.2.11 Reporting an Exception

5.2.12 Determining Whether Two Exceptions Match

5.3 C Language Syntax

5.4 Rules and Conventions for Modular Use of Exceptions

5.5 DECthreads Exceptions and Definitions

6 DECthreads Example

6.1 Prime Number Search Example

Part II POSIX 1003.1c (pthread) Routines Reference

pthread_atfork

pthread_attr_destroy

pthread_attr_getdetachstate

pthread_attr_getguardsize_np

pthread_attr_getinheritsched

pthread_attr_getschedparam

pthread_attr_getschedpolicy

pthread_attr_getstacksize

pthread_attr_init

pthread_attr_setdetachstate

pthread_attr_setguardsize_np

pthread_attr_setinheritsched

pthread_attr_setschedparam

pthread_attr_setschedpolicy

pthread_attr_setstacksize

pthread_cancel

pthread_cleanup_pop

pthread_cleanup_push

pthread_cond_broadcast

pthread_cond_destroy

pthread_cond_init

pthread_cond_signal

pthread_cond_signal_int_np

pthread_cond_timedwait

pthread_cond_wait

pthread_condattr_destroy

pthread_condattr_init

pthread_get_expiration_np

pthread_getschedparam

pthread_getsequence_np

pthread_lock_global_np

pthread_mutex_destroy

pthread_mutex_init

pthread_mutex_lock

pthread_mutex_trylock

pthread_mutex_unlock

pthread_mutexattr_destroy

pthread_mutexattr_gettype_np

pthread_mutexattr_init

pthread_mutexattr_settype_np

pthread_once

pthread_self

pthread_setcancelstate

pthread_setcanceltype

pthread_setschedparam

pthread_setspecific

pthread_sigmask

pthread_testcancel

pthread_unlock_global_np

sched_yield

Part III Digital Proprietary Interfaces: tis Routines Reference

Part IV Appendices

A Considerations for Digital UNIX Systems

A.1 Overview

A.2 Building with DECthreads

A.2.1 Including DECthreads Header Files

A.2.2 Building Multithreaded Applications Libraries

A.2.3 Building Applications That Use the CMA Or Draft 4 POSIX 1003.4a Interfaces

A.2.4 Linking Multithreaded Shared Libraries

A.2.5 Compiling Applications That Use the Thread-Independent Services (tis) Interface

A.3 Two-Level Scheduling on Digital Unix

A.3.1 DECthreads Use of Kernel Threads

A.3.2 Support for Real-Time Scheduling on Digital UNIX Systems

A.4 Thread Cancelability of System Services

A.4.1 Current Cancellation Points

A.4.2 Future Cancellation Points

A.5 Using Signals

A.5.1 POSIX sigwait Service

A.5.2 Handling Signals as Exceptions

A.6 Dynamic Activation

B Considerations for OpenVMS Systems

B.1 Overview

B.2 Including DECthreads Header Files

B.3 Compiling OpenVMS Images

B.4 Compiling OpenVMS Images Using the POSIX 1003.4a Draft 4 Standard

B.5 Linking OpenVMS Images

B.6 Using DECthreads with Asynchronous System Trap (AST) Routines

B.7 Dynamic Activation

B.8 Declaring an OpenVMS Condition Handler

B.9 Thread Cancelability of System Services

B.10 Using OpenVMS Alpha 64-Bit Addressing

B.11 DECthreads Condition Values

B.12 Two-Level Scheduling on OpenVMS Alpha

B.12.1 DECthreads Virtual Processors

B.12.2 AST delivery

B.12.3 Blocking System Services

B.12.4 $HIBER and $WAKE

B.12.5 Event Flags

B.12.6 Interactions with OpenVMS

B.12.7 Image Exit

B.12.8 Sysgen Parameter

B.12.9 Process Control System Services and DCL Commands

B.12.9.1 Process-Level System Services

B.12.9.2 Kernel-Level System Services

B.12.9.3 DCL Commands

C Considerations for Windows NT and Windows 95 Systems

C.1 Using DECthreads Routines on Windows NT and Windows 95 Systems

C.2 Compiling DECthreads Applications

C.3 Linking DECthreads Applications

C.4 File Naming Support for DECthreads Header Files

C.5 Win32/DECthreads API Interoperability

C.6 Restrictions for Win32 API Routines

C.7 Thread Cancelability of System Services

C.8 Unsupported DECthreads Interface Routines

C.9 Use Restrictions of cma_delay and pthread_delay_np Routines

C.10 Timing Issues

D Debugging Multithreaded Applications

D.1 DECthreads Debugger

D.1.1 Interactive Debugging

D.1.2 Noninteractive Debugging

D.1.3 Running DECthreads in Metered Mode

D.1.4 DECthreads Debugger Commands

D.1.4.1 Conditions Command

D.1.4.2 Exit and Quit Commands

D.1.4.3 Help Command

D.1.4.4 Keys Command

D.1.4.5 Mutexes Command

D.1.4.6 Show Command

D.1.4.7 Stack Command

D.1.4.8 System Command

D.1.4.9 Threads Command

D.1.4.10 Versions Command

D.2 Using ladebug on Digital UNIX

D.3 Debugging Threads on Windows NT Systems

E Digital Proprietary Interface Routines: CMA

E.1 Migrating from a cma Interface to POSIX 1003.1c

E.1.1 cma Handles

E.1.2 Interface Routine Mapping

E.1.3 New POSIX 1003.1c Routines

E.2 Atomic Queues

E.3 Scheduling Parameters

E.4 cma Exceptions

E.5 cma Alert Example

E.6 cma Routine Descriptions

cma_alert_disable_asynch

cma_alert_disable_general

cma_alert_enable_asynch

cma_alert_enable_general

cma_attr_get_guardsize

cma_attr_get_inherit_sched

cma_attr_get_mutex_kind

cma_attr_get_priority

cma_attr_get_sched

cma_attr_get_stacksize

cma_attr_set_guardsize

cma_attr_set_inherit_sched

cma_attr_set_mutex_kind

cma_attr_set_priority

cma_attr_set_sched

cma_attr_set_stacksize

cma_stack_check_limit_np

cma_thread_alert

cma_thread_bind_to_cpu

cma_thread_create

cma_thread_detach

cma_thread_exit_error

cma_thread_exit_normal

cma_thread_get_priority

cma_thread_get_sched

cma_thread_get_self

cma_thread_join

cma_thread_set_priority

cma_thread_set_sched

cma_time_get_expiration

cma_unlock_global

cma_yield

F DECthreads Library Routines

cma_lib_attr_create

cma_lib_attr_delete

cma_lib_attr_get_queuesize

cma_lib_attr_set_queuesize

cma_lib_queue_create

cma_lib_queue_delete

cma_lib_queue_dequeue

cma_lib_queue_enqueue

cma_lib_queue_requeue

cma_lib_queue_try_dequeue

cma_lib_queue_try_enqueue

cma_lib_queue_try_enqueue_int

cma_lib_queue_try_requeue

G POSIX 1003.4a (Draft 4) pthread Routines

G.1 Migrating from a 1003.4a Interface to POSIX 1003.1c

G.1.1 Error Status and Function Returns

G.1.2 Replaced or Renamed Routines

G.1.3 Routines with No Changes to Syntax

G.1.4 Routines with Prototype or Syntax Changes

G.1.5 New Routines

pthread_attr_create

pthread_attr_delete

pthread_attr_getdetach_np

pthread_attr_getguardsize_np

pthread_attr_getinheritsched

pthread_attr_getprio

pthread_attr_getsched

pthread_attr_getstacksize

pthread_attr_setdetach_np

pthread_attr_setguardsize_np

pthread_attr_setinheritsched

pthread_attr_setprio

pthread_attr_setsched

pthread_attr_setstacksize

pthread_bind_to_cpu_np

pthread_cancel

pthread_cleanup_pop

pthread_cleanup_push

pthread_condattr_create

pthread_condattr_delete

pthread_cond_broadcast

pthread_cond_destroy

pthread_cond_init

pthread_cond_signal

pthread_cond_signal_int_np

pthread_cond_sig_preempt_int_np

pthread_cond_timedwait

pthread_get_expiration_np

pthread_lock_global_np

pthread_mutexattr_create

pthread_mutexattr_delete

pthread_mutexattr_getkind_np

pthread_mutexattr_setkind_np

pthread_mutex_destroy

pthread_mutex_init

pthread_mutex_lock

pthread_mutex_trylock

pthread_mutex_unlock

pthread_once

pthread_self

pthread_setasynccancel

pthread_unlock_global_np

pthread_yield

Glossary

Index

Examples

2-1 pthread Cancel Example

6-1 C Program Example (Prime Number Search)

E-1 cma Alert Example

Figures

1-1 Single Threaded Process

1-2 Multithreaded Process

1-3 Thread State Transitions

1-4 Work Crew Model of Thread Operation

1-5 Pipelining Model of Thread Operation

2-1 Only One Thread Can Lock a Mutex

2-2 Thread A Waits on Condition Ready

2-3 Thread B Signals Condition Ready

2-4 Thread A Wakes and Proceeds

2-5 Flow with FIFO Scheduling

2-6 Flow with RR Scheduling

2-7 Flow with Default Scheduling

4-1 Readers/Writer Lock Behavior

Tables

1 Telephone and Direct Mail Orders

2 Conventions

1-1 DECthreads POSIX 1003.1c Routines Summary

1-2 DECthreads Routines Summary

5-1 pthread Exceptions

A-1 DECthreads Header Files

A-2 Digital UNIX Shared Libraries for Multithreaded Programs

A-3 Signals Reported as Exceptions

B-1 DECthreads Header Files

B-2 DECthreads Images

B-3 DECthreads Condition Values

D-1 DECthreads Debugging Return Status

E-1 cma Exceptions

Table of Contents