Guide to DECthreads

Contents (summary)

• Part 1 DECthreads Overview and Programming Guidelines
• Chapter 1 Introducing DECthreads for Multithreaded Programming
• Chapter 2 DECthreads Objects and Operations
• Chapter 3 Programming with Threads
• Chapter 4 Writing Thread-Safe Libraries
• Chapter 5 Using the DECthreads Exception Package
• Chapter 6 DECthreads Examples
• Part 2 POSIX.1c (pthread) Routines Reference
• Part 3 DIGITAL-Proprietary Interfaces: tis Routines Reference
• Part 4 Appendixes
• Appendix A Considerations for DIGITAL UNIX Systems
• Appendix B Considerations for OpenVMS Systems
• Appendix C Considerations for Windows NT Systems
• Appendix D Debugging Multithreaded Applications
• Appendix E Migrating from the cma Interface
• Appendix F Migrating from the d4 Interface
• Glossary
• Index
• Figures
• Examples
• Tables

Contents

• ---

  Part 1 DECthreads Overview and Programming Guidelines

• ---

  Chapter 1 Introducing DECthreads for Multithreaded Programming
  • 1.1 Advantages of Using Threads
  • 1.2 Overview of Threads
  • 1.3 Thread Execution
  • 1.4 Functional Models for Multithreaded Programming
    • 1.4.1 Boss/Worker Model
    • 1.4.2 Work Crew Model
    • 1.4.3 Pipelining Model
    • 1.4.4 Combination of Functional Models
  • 1.5 Potential Issues for Multithreaded Programs
  • 1.6 DECthreads Libraries and Interfaces
    • 1.6.1 Multithreading pthread Interface
      • 1.6.1.1 Optionally Implemented POSIX.1c-1995 Routines
    • 1.6.2 Thread-Independent Services Interface
    • 1.6.3 Undocumented and Obsolete DECthreads Interfaces
      • 1.6.3.1 Undocumented But Supported cma Interface
      • 1.6.3.2 Obsolete d4 Interfaces

• ---

  Chapter 2 DECthreads Objects and Operations
  • 2.1 Threads, Mutexes, and Condition Variables
  • 2.2 Attributes Objects
  • 2.3 Thread Objects and Operations
    • 2.3.1 Creating and Starting a Thread
    • 2.3.2 Setting the Attributes of a New Thread
      • 2.3.2.1 Setting the Inherit Scheduling Attribute
      • 2.3.2.2 Setting the Scheduling Policy Attribute
        • 2.3.2.2.1 Techniques for Setting the Scheduling Policy Attribute
        • 2.3.2.2.2 Comparing Throughput and Real-Time Policies
        • 2.3.2.2.3 Portability of Scheduling Policy Settings
      • 2.3.2.3 Setting the Scheduling Parameters Attribute
      • 2.3.2.4 Setting the Stacksize Attribute
      • 2.3.2.5 Setting the Stack Address Attribute
      • 2.3.2.6 Setting the Guardsize Attribute
      • 2.3.2.7 Setting the Contention Scope Attribute
    • 2.3.3 Terminating a Thread
      • 2.3.3.1 Cleanup Handlers
    • 2.3.4 Detaching and Destroying a Thread
    • 2.3.5 Joining With a Thread
    • 2.3.6 Scheduling a Thread
      • 2.3.6.1 Calculating the Scheduling Priority
      • 2.3.6.2 Effects of Scheduling Policy
    • 2.3.7 Canceling a Thread
      • 2.3.7.1 Thread Cancelation Implemented Using Exceptions
      • 2.3.7.2 Thread Return Value After Cancelation
      • 2.3.7.3 Controlling Thread Cancelation
      • 2.3.7.4 Cancelation Points
      • 2.3.7.5 Cleanup from Synchronous Cancelation
      • 2.3.7.6 Cleanup from Asynchronous Cancelation
      • 2.3.7.7 Example of Thread Cancelation Code
  • 2.4 Synchronization Objects
    • 2.4.1 Mutexes
      • 2.4.1.1 Normal Mutex
      • 2.4.1.2 Default Mutex
      • 2.4.1.3 Recursive Mutex
      • 2.4.1.4 Errorcheck Mutex
      • 2.4.1.5 Mutex Operations
      • 2.4.1.6 Mutex Attributes
    • 2.4.2 Condition Variables
    • 2.4.3 Condition Variable Attributes
  • 2.5 Thread-Specific Data

• ---

  Chapter 3 Programming with Threads
  • 3.1 Designing Code for Asynchronous Execution
    • 3.1.1 Avoid Passing Stack Local Data
    • 3.1.2 Initialize DECthreads Objects Before Thread Creation
    • 3.1.3 Don't Use Scheduling As Synchronization
  • 3.2 Memory Synchronization Between Threads
  • 3.3 Using Shared Memory
    • 3.3.1 Using Static Memory
    • 3.3.2 Using Stack Memory
    • 3.3.3 Using Dynamic Memory
  • 3.4 Managing a Thread's Stack
    • 3.4.1 Sizing the Stack
    • 3.4.2 Using a Stack Guard Area
    • 3.4.3 Handling Stack Overflow
  • 3.5 Scheduling Issues
    • 3.5.1 Real-Time Scheduling
    • 3.5.2 Priority Inversion
    • 3.5.3 Dependencies Among Scheduling Attributes and Contention Scope
  • 3.6 Using Synchronization Objects
    • 3.6.1 Distinguishing Proper Usage of Mutexes and Condition Variables
    • 3.6.2 Avoiding Race Conditions
    • 3.6.3 Avoiding Deadlocks
    • 3.6.4 Signaling a Condition Variable
  • 3.7 One-Time Initialization
  • 3.8 Managing Dependencies Upon Other Libraries
    • 3.8.1 Thread Reentrancy
    • 3.8.2 Thread Safety
    • 3.8.3 Lacking Thread Safety
      • 3.8.3.1 Using Mutex Around Call to Unsafe Code
      • 3.8.3.2 Using or Copying Static Data Before Releasing the Mutex
      • 3.8.3.3 Using the DECthreads Global Lock
    • 3.8.4 Use of Multiple Threads Libraries Not Supported
  • 3.9 Detecting DECthreads Error Conditions
    • 3.9.1 Contents of a DECthreads Bugcheck Dump File
    • 3.9.2 Interpreting a DECthreads Bugcheck

• ---

  Chapter 4 Writing Thread-Safe Libraries
  • 4.1 Features of the tis Interface
    • 4.1.1 Reentrant Code Required
    • 4.1.2 Performance of tis Interface Routines
    • 4.1.3 Run-Time Linkage of tis Interface Routines
    • 4.1.4 Cancelation Points
  • 4.2 Using Mutexes
  • 4.3 Using Condition Variables
  • 4.4 Using Thread-Specific Data
  • 4.5 Using Read-Write Locks

• ---

  Chapter 5 Using the DECthreads Exception Package
  • 5.1 About the DECthreads Exceptions Package
    • 5.1.1 Supported Programming Languages
    • 5.1.2 Relation of Exceptions to Return Codes and Signals
  • 5.2 Why Use Exceptions
  • 5.3 Exception Programming
    • 5.3.1 Declaring and Initializing an Exception
    • 5.3.2 Raising an Exception
    • 5.3.3 Catching an Exception
    • 5.3.4 Reraising an Exception
    • 5.3.5 Expressing Epilogue Actions
  • 5.4 Exception Objects
    • 5.4.1 Declaring and Initializing Exception Objects
    • 5.4.2 Address Exceptions and Status Exceptions
    • 5.4.3 How Exceptions Terminate
  • 5.5 Exception Scopes
  • 5.6 Raising Exceptions
  • 5.7 Exception Handling Macros
    • 5.7.1 Context of the Handler
    • 5.7.2 Handlers and Macros
    • 5.7.3 Catching Specific Exceptions
    • 5.7.4 Catching Unspecified Exceptions
    • 5.7.5 Reraising the Current Exception
    • 5.7.6 Defining Epilogue Actions
  • 5.8 Operations on Exceptions
    • 5.8.1 Referencing the Caught Exception
    • 5.8.2 Setting a System-Defined Error Status
    • 5.8.3 Obtaining a System-Defined Error Status
    • 5.8.4 Reporting a Caught Exception
    • 5.8.5 Determining Whether Two Exceptions Match
  • 5.9 Conventions for Modular Use of Exceptions
    • 5.9.1 Develop Naming Conventions for Exceptions
    • 5.9.2 Enclose Appropriate Actions in an Exception Scope
    • 5.9.3 Raise Exceptions Prior to Performing Side-Effects
    • 5.9.4 Distinguish Raising Exceptions From Side-Effects
    • 5.9.5 Declare Variables Within Handler Code as Volatile
    • 5.9.6 Reraise Caught Exceptions That Are Not Fully Handled
    • 5.9.7 Declare All Exception Objects as Static
  • 5.10 Exceptions Defined by DECthreads
  • 5.11 Interoperability of Language-Specific Exceptions
  • 5.12 Host Operating System Dependencies
    • 5.12.1 No DIGITAL UNIX Dependencies
    • 5.12.2 OpenVMS Conditions and DECthreads Exceptions

• ---

  Chapter 6 DECthreads Examples
  • 6.1 Prime Number Search Example
  • 6.2 Asynchronous User Interface Example

• ---

  Part 2 POSIX.1c (pthread) Routines Reference
  • Command 1 pthread_atfork
  • Command 2 pthread_attr_destroy
  • Command 3 pthread_attr_getdetachstate
  • Command 4 pthread_attr_getguardsize
  • Command 5 pthread_attr_getguardsize_np
  • Command 6 pthread_attr_getinheritsched
  • Command 7 pthread_attr_getname_np
  • Command 8 pthread_attr_getschedparam
  • Command 9 pthread_attr_getschedpolicy
  • Command 10 pthread_attr_getscope
  • Command 11 pthread_attr_getstackaddr
  • Command 12 pthread_attr_getstacksize
  • Command 13 pthread_attr_init
  • Command 14 pthread_attr_setdetachstate
  • Command 15 pthread_attr_setguardsize
  • Command 16 pthread_attr_setguardsize_np
  • Command 17 pthread_attr_setinheritsched
  • Command 18 pthread_attr_setname_np
  • Command 19 pthread_attr_setschedparam
  • Command 20 pthread_attr_setschedpolicy
  • Command 21 pthread_attr_setscope
  • Command 22 pthread_attr_setstackaddr
  • Command 23 pthread_attr_setstacksize
  • Command 24 pthread_cancel
  • Command 25 pthread_cleanup_pop
  • Command 26 pthread_cleanup_push
  • Command 27 pthread_condattr_destroy
  • Command 28 pthread_condattr_init
  • Command 29 pthread_cond_broadcast
  • Command 30 pthread_cond_destroy
  • Command 31 pthread_cond_getname_np
  • Command 32 pthread_cond_init
  • Command 33 pthread_cond_setname_np
  • Command 34 pthread_cond_signal
  • Command 35 pthread_cond_signal_int_np
  • Command 36 pthread_cond_timedwait
  • Command 37 pthread_cond_wait
  • Command 38 pthread_create
  • Command 39 pthread_delay_np
  • Command 40 pthread_detach
  • Command 41 pthread_equal
  • Command 42 pthread_exc_get_status_np
  • Command 43 pthread_exc_matches_np
  • Command 44 pthread_exc_report_np
  • Command 45 pthread_exc_set_status_np
  • Command 46 pthread_exit
  • Command 47 pthread_getconcurrency
  • Command 48 pthread_getname_np
  • Command 49 pthread_getschedparam
  • Command 50 pthread_getsequence_np
  • Command 51 pthread_getspecific
  • Command 52 pthread_get_expiration_np
  • Command 53 pthread_join
  • Command 54 pthread_key_create
  • Command 55 pthread_key_delete
  • Command 56 pthread_key_getname_np
  • Command 57 pthread_key_setname_np
  • Command 58 pthread_kill
  • Command 59 pthread_lock_global_np
  • Command 60 pthread_mutexattr_destroy
  • Command 61 pthread_mutexattr_gettype
  • Command 62 pthread_mutexattr_gettype_np
  • Command 63 pthread_mutexattr_init
  • Command 64 pthread_mutexattr_settype
  • Command 65 pthread_mutexattr_settype_np
  • Command 66 pthread_mutex_destroy
  • Command 67 pthread_mutex_getname_np
  • Command 68 pthread_mutex_init
  • Command 69 pthread_mutex_lock
  • Command 70 pthread_mutex_setname_np
  • Command 71 pthread_mutex_trylock
  • Command 72 pthread_mutex_unlock
  • Command 73 pthread_once
  • Command 74 pthread_self
  • Command 75 pthread_setcancelstate
  • Command 76 pthread_setcanceltype
  • Command 77 pthread_setconcurrency
  • Command 78 pthread_setname_np
  • Command 79 pthread_setschedparam
  • Command 80 pthread_setspecific
  • Command 81 pthread_sigmask
  • Command 82 pthread_testcancel
  • Command 83 pthread_unlock_global_np
  • Command 84 sched_get_priority_max
  • Command 85 sched_get_priority_min
  • Command 86 sched_yield
  • Command 87 sigwait

• ---

  Part 3 DIGITAL-Proprietary Interfaces: tis Routines Reference
  • Command 88 tis_cond_broadcast
  • Command 89 tis_cond_destroy
  • Command 90 tis_cond_init
  • Command 91 tis_cond_signal
  • Command 92 tis_cond_wait
  • Command 93 tis_getspecific
  • Command 94 tis_key_create
  • Command 95 tis_key_delete
  • Command 96 tis_lock_global
  • Command 97 tis_mutex_destroy
  • Command 98 tis_mutex_init
  • Command 99 tis_mutex_lock
  • Command 100 tis_mutex_trylock
  • Command 101 tis_mutex_unlock
  • Command 102 tis_once
  • Command 103 tis_read_lock
  • Command 104 tis_read_trylock
  • Command 105 tis_read_unlock
  • Command 106 tis_rwlock_destroy
  • Command 107 tis_rwlock_init
  • Command 108 tis_self
  • Command 109 tis_setcancelstate
  • Command 110 tis_setspecific
  • Command 111 tis_testcancel
  • Command 112 tis_unlock_global
  • Command 113 tis_write_lock
  • Command 114 tis_write_trylock
  • Command 115 tis_write_unlock

• ---

  Part 4 Appendixes

• ---

  Appendix A Considerations for DIGITAL UNIX Systems
  • A.1 Overview
  • A.2 Building DECthreads Applications
    • A.2.1 Including DECthreads Header Files
    • A.2.2 Building Multithreaded Applications from DECthreads Libraries
    • A.2.3 Linking Multithreaded Shared Libraries
    • A.2.4 Compiling Applications With the tis Interface
  • A.3 Two-Level Scheduling on DIGITAL UNIX Systems
    • A.3.1 DECthreads Use of Kernel Threads
    • A.3.2 Support for Real-Time Scheduling
  • A.4 Thread Cancelability of System Services
    • A.4.1 Current Cancelation Points
    • A.4.2 Future Cancelation Points
  • A.5 Using Signals
    • A.5.1 POSIX sigwait Service
    • A.5.2 Handling Synchronous Signals as Exceptions
  • A.6 Thread Stack Guard Areas
  • A.7 Dynamic Activation

• ---

  Appendix B Considerations for OpenVMS Systems
  • B.1 Overview
  • B.2 Compiling Under OpenVMS
  • B.3 Linking OpenVMS Images
  • B.4 Using DECthreads with AST Routines
  • B.5 Dynamic Activation
  • B.6 Declaring an OpenVMS Condition Handler
  • B.7 Thread Cancelability of System Services
  • B.8 Using OpenVMS Alpha 64-Bit Addressing
  • B.9 DECthreads Condition Values
  • B.10 Two-Level Scheduling on OpenVMS Alpha Systems
    • B.10.1 Linker Options to Specify Image's Use of Kernel Threads
    • B.10.2 Setting Kernel Threads Support in Existing Images
      • B.10.2.1 Examples
    • B.10.3 Querying and Setting Kernel Threads Features
    • B.10.4 Creation of Virtual Processors
    • B.10.5 Delivery of ASTs
    • B.10.6 Blocking System Services
    • B.10.7 $HIBER and $WAKE
    • B.10.8 Event Flags
    • B.10.9 Interactions with OpenVMS
    • B.10.10 Image Exit
    • B.10.11 SYSGEN Parameter MULTITHREAD
    • B.10.12 Process Control System Services and DCL Commands
      • B.10.12.1 Process-Level System Services
      • B.10.12.2 Kernel-Level System Services
      • B.10.12.3 DCL Commands
  • B.11 Interoperability with POSIX for OpenVMS

• ---

  Appendix C Considerations for Windows NT Systems
  • C.1 DECthreads Interfaces on Windows NT Systems
    • C.1.1 Pthread Interface
    • C.1.2 Other Interfaces
  • C.2 Compiling DECthreads Applications
  • C.3 Linking DECthreads Applications
  • C.4 Interoperability of Win32 API and DECthreads pthread Routines
  • C.5 Thread Cancelability of System Services

• ---

  Appendix D Debugging Multithreaded Applications
  • D.1 Using PTHREAD_CONFIG
    • D.1.1 Major and Minor Keywords
    • D.1.2 Specifying Multiple Values
  • D.2 Running DECthreads in Metered Mode
  • D.3 Using Ladebug on DIGITAL UNIX
  • D.4 Debugging Threads on OpenVMS Systems
    • D.4.1 Display of Stack Trace from Unhandled Exception
  • D.5 Debugging Threads on Windows NT Systems

• ---

  Appendix E Migrating from the cma Interface
  • E.1 Overview
  • E.2 cma Handles
  • E.3 Interface Routine Mapping
  • E.4 New pthread Routines

• ---

  Appendix F Migrating from the d4 Interface
  • F.1 Overview
  • F.2 Error Status and Function Returns
  • F.3 Replaced or Renamed Routines
  • F.4 Routines with No Changes to Syntax
  • F.5 Routines with Prototype or Syntax Changes
  • F.6 New Routines

• ---

  Glossary

• ---

  Index

• ---

  Examples
  • 2-1 pthread Cancel
  • 5-1 Raising an Exception
  • 5-2 Catching an Exception Using CATCH
  • 5-3 Catching an Exception Using CATCH and CATCH_ALL
  • 5-4 Defining Epilogue Actions Using FINALLY
  • 5-5 Defining an Exception Scope
  • 5-6 Raising a DECthreads Exception
  • 5-7 Catching a Specific Exception Using CATCH
  • 5-8 Catching an Unspecified Exception Using CATCH_ALL
  • 5-9 Reraising an Exception Using RERAISE
  • 5-10 Defining Epilogue Actions Using FINALLY
  • 5-11 Setting an Error Status in an Exception Object
  • 5-12 Obtaining the Error Status Value from a Status Exception Object
  • 5-13 Reporting a Caught Exception
  • 5-14 Comparing Two Exception Objects
  • 5-15 Incorrect Placement of Statements That Might Raise an Exception
  • 5-16 Correct Placement of Statements That Might Raise an Exception
  • 5-17 Correct Placement of Statements That Might Raise an Exception
  • 6-1 C Program Example (Prime Number Search)
  • 6-2 C Program Example (Asynchronous User Interface)

• ---

  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 Flow with FIFO Scheduling
  • 2-2 Flow with RR Scheduling
  • 2-3 Flow with Default Scheduling
  • 2-4 Only One Thread Can Lock a Mutex
  • 2-5 Thread A Waits on Condition Ready
  • 2-6 Thread B Signals Condition Ready
  • 2-7 Thread A Wakes and Proceeds
  • 4-1 Read-Write Lock Behavior

• ---

  Tables
  • 1-Conventions
  • 1-1 DECthreads pthread Routines Summary
  • 1-2 DECthreads tis Routines Summary
  • 5-1 Names of Exception Objects Defined by DECthreads
  • 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
  • B-4 Results of Keyword Arguments to /THREADS_ENABLE Qualifier
  • B-5 Return Values from$GETJPI System Service
  • D-1 PTHREAD_CONFIG Settings
  • E-1 Corresponding cma and pthread Routines
  • F-1 pthread Routines That Replace d4 Routines
  • F-2 d4 Routines With Syntax Changes as pthread Routines
  • F-3 d4 Routines Whose pthread Counterpart Uses Standard Datatypes