HP OpenVMS Systems Documentation

Guide to the POSIX Threads Library

Contents

Index

Appendix E
Migrating from the d4 Interface

This appendix provides migration information for the routines in the POSIX 1003.4a/Draft 4 (or d4) interface.

Note

Applications that use the d4 routines require significant modification to be migrated to the pthread interface described in Part 2.

E.1 Overview

Routines in the pthread interface differ significantly from the original POSIX 1003.4a/Draft 4 implementation. This section describes the major changes between the interfaces.

E.2 Error Status and Function Returns

The pthread interface does not use the global variable errno. (Note that the Threads Library provides a thread-specific errno for use by libraries and application code, but the pthread interface does not write to it.)

If an error condition occurs, a pthread routine returns an integer value that indicates the type of error. For example, a call to the d4 interface's implementation of pthread_cond_destroy() that returned a --1 and set errno to [EBUSY], returns [EBUSY] as the routine's return value in the pthread interface implementation.

On successful completion, most pthread interface routines return zero (0).

E.3 Replaced or Renamed Routines

Many routines in the d4 interface have been replaced or renamed in the pthread interface, as shown in Table E-1.

**Table E-1 pthread Routines That Replace d4 Routines**
d4 Routine	Replacement pthread Routine
`pthread_attr_create()`	`pthread_attr_init()`
`pthread_attr_delete()`	`pthread_attr_destroy()`
`pthread_attr_set/getdetach_np()`	`pthread_attr_set/getdetachstate()`
`pthread_attr_set/getguardsize_np()`	`pthread_attr_set/getguardsize()`
`pthread_attr_set/getprio()`	`pthread_attr_set/getschedparam()`
`pthread_attr_set/getsched()`	`pthread_attr_set/getschedpolicy()`
`pthread_condattr_create()`	`pthread_condattr_init()`
`pthread_condattr_delete()`	`pthread_condattr_destroy()`
`pthread_keycreate()`	`pthread_key_create()`
`pthread_mutexattr_create()`	`pthread_mutexattr_init()`
`pthread_mutexattr_delete()`	`pthread_mutexattr_destroy()`
`pthread_mutexattr_get/setkind_np()`	`pthread_mutexattr_get/settype()`
`pthread_setasynccancel()`	`pthread_setcanceltype()`
`pthread_setcancel()`	`pthread_setcancelstate()`
`pthread_set/getprio()`	`pthread_set/getschedparam()`
`pthread_set/getscheduler()`	`pthread_set/getschedparam()`
`pthread_yield()`	`sched_yield()`

E.4 Routines with No Changes to Syntax

Except for the return value, the following routines in the d4 interface have no changes to syntax in the pthread interface:

pthread_attr_setinheritsched()
pthread_cancel()
pthread_cond_broadcast()
pthread_cond_destroy()
pthread_cond_signal()
pthread_cond_signal_int_np()
pthread_cond_timedwait()
pthread_cond_wait()
pthread_delay_np()
pthread_equal()
pthread_exit()
pthread_get_expiration_np()
pthread_join() (now detaches the thread)
pthread_mutex_destroy()
pthread_mutex_lock()
pthread_mutex_trylock()
pthread_mutex_unlock()
pthread_once()

The following routines have no changes in syntax or return value:

pthread_self()
pthread_testcancel()

Notice that the d4 routine pthread_cond_timedwait() requires the time argument abstime to be specified in local time; whereas the pthread routine pthread_cond_timedwait() requires the time argument abstime to be specified in Universal Coordinated Time (UTC).

E.5 Routines with Prototype or Syntax Changes

Table E-2 shows the routines in the d4 interface that have changes to their argument syntax in the pthread interface.

**Table E-2 d4 Routines With Syntax Changes as pthread Routines**
Old Syntax	New Syntax
`int pthread_attr_getinheritsched( pthread_attr_t attr)`	`int pthread_attr_getinheritsched( const pthread_attr_t * attr, int * inheritsched)`
`unsigned long pthread_attr_getstacksize( pthread_attr_t attr)`	`int pthread_attr_getstacksize( const pthread_attr_t * attr, size_t * stacksize)`
`unsigned long pthread_attr_setstacksize( pthread_attr_t * attr, long stacksize)`	`int pthread_attr_setstacksize( const pthread_attr_t * attr, size_t stacksize)`
`int pthread_cleanup_pop( int execute)`	`void pthread_cleanup_pop( int execute)`
`int pthread_cond_init( pthread_cond_t * cond, pthread_condattr_t attr)`	`int pthread_cond_init( pthread_cond_t * cond, pthread_condattr_t * attr)`
`int pthread_create( pthread_t * thread, pthread_attr_t attr, pthread_startroutine_t start_routine, pthread_addr_t arg)`	`int pthread_create( pthread_t * thread, const pthread_attr_t * attr, void* (* start_routine)(void ), void arg)`
`int pthread_detach( pthread_t * thread)`	`int pthread_detach( pthread_t thread)`
`int pthread_getspecific( pthread_key_t key, void ** value)`	`void * pthread_getspecific( pthread_key_t key)`
`void pthread_lock_global_np()`	`int pthread_lock_global_np(void)`
`void pthread_unlock_global_np()`	`int pthread_unlock_global_np(void)`
`int pthread_mutex_init( pthread_mutex_t * mutex, pthread_mutexattr_t attr)`	`int pthread_mutex_init( pthread_mutex_t * mutex, const pthread_mutexattr_t * attr)`

Table E-3 shows routines in the d4 interface that have a corresponding pthread routine that does not support the obsolete d4-style datatypes. These datatypes were documented for previous releases of the Threads Library.

If your original code used the standard Threads Library datatypes, then this migration requirement might not impact your code.

**Table E-3 d4 Routines Whose pthread Counterpart Uses Standard Datatypes**
New Standard Datatype Syntax	Nonstandard Datatype Syntax
`void pthread_cleanup_push( void (* routine)(void ), void arg)`	`int pthread_cleanup_push( pthread_cleanup_t * routine, pthread_addr_t arg)`
`int pthread_create( pthread_t * thread, const pthread_attr_t * attr, void ( start_routine)(void ), void arg)`	`int pthread_create( pthread_t * thread, pthread_attr_t attr, pthread_startroutine_t start_routine, pthread_addr_t arg)`
`int pthread_exit( void * value_ptr)`	`int pthread_exit( pthread_addr_t status)`
`void * pthread_getspecific( pthread_key_t key)`	`int pthread_getspecific( pthread_key_t key, pthread_addr_t * value)`
`int pthread_join( pthread_t thread, void ** value_ptr)`	`int pthread_join( pthread_t thread, pthread_addr_t * status)`
`int pthread_once( pthread_once_t * once_control, void (* init_routine)(void))`	`int pthread_once( pthread_once_t * once_block, pthread_initroutine_t init_routine)`
`int pthread_setspecific( pthread_key_t key, const void * value)`	`int pthread_setspecific( pthread_key_t key, pthread_addr_t value)`

E.6 New Routines

The following are routines in the pthread interface that did not exist at the time of the implementation of the d4 interface:

pthread_atfork() (Tru64 UNIX only)
pthread_attr_getscope()
pthread_attr_setscope()
pthread_key_delete()
pthread_kill() (Tru64 UNIX only)
All pthread_rwlockattr_ and pthread_rwlock_ routines
pthread_sigmask() (Tru64 UNIX only)
All _getpshared and _setpshared routines

Glossary

actual granularity: Granularity for a program; limited by the granularities made available by the processor, but determined by the code produced by the compiler. See also granularity, natural granularity, and system granularity.

address exception: An exception whose identity is based on where in the program it was raised. See also exception and status exception.

alert: See cancelation request.

alertable routine: See cancelable routine.

AST: Mechanism that signals an asynchronous event to a process.

asynchronous cancelability: If enabled, allows a thread to receive a cancelation request at any time (not only at cancelation points). See also general cancelability.

asynchronous signal: Signal that is the result of an event that is external to the process and is delivered at any point in a thread's execution when such an event occurs. See also synchronous signal.

attributes: Individual components of the attributes object. Attributes specify detailed properties about the objects to be created. See also attributes object.

attributes object: Object used to describe Threads Library objects (thread, mutex, condition variable, or queue). This description consists of the individual attribute values that are used to create an object. See also attributes.

bugcheck: An error condition internal to the Threads Library run-time environment that causes it to produce a specially formatted error message. Output of this message can be controlled using the PTHREAD_CONFIG environment variable or logical symbol.

cancelability state: Attribute of a thread that determines whether it currently receives cancelation requests.

cancelability type: Attribute of a thread that determines whether it responds to a cancelation request at cancelation points (synchronous cancelation) or at any point in its execution (asynchronous cancelation).

cancelation point: A routine that, when called, determines whether a cancelation request is pending for this thread.

cancelation request: Mechanism by which one thread requests termination of another thread (or itself).

condition variable: Object that allows a thread to block its own execution until some shared data reaches a particular state.

condition variable attributes object: Object that allows you to specify values for condition variable attributes when you create a condition variable.

contention scope: Attribute of a thread that specifies the set of threads with which it competes for processing resources. See also process contention scope and system contention scope.

deadlock: Condition involving one or more threads and a set of one or more resources in which each of the threads is blocked waiting for one of the resources and all of the resources are held by the threads such that none of the threads can continue. For example, a thread will enter a self-deadlock when it attempts to lock a normal mutex a second time. Likewise, two threads will enter a deadlock when each attempts to lock a second mutex that is already held by the other. The introduction of additional threads and synchronization objects allows for more complex deadlock configurations.

dynamic memory: Memory that is allocated by the program as a result of a call to some memory management function, and that is referenced through pointer variables. See also static memory and stack memory.

epilogue code: Block of code, associated with a Threads Library exception scope, that finalizes the context of an exception scope. Epilogue code is always executed, regardless of whether the code in the associated exception scope raised an exception.

errorcheck mutex: Mutex that can be locked exactly once by a thread, like a normal mutex. If a thread tries to lock the mutex again without first unlocking it, the thread receives an error instead of deadlocking. See also deadlock, mutex, normal mutex, and recursive mutex.

exception: Object that describes an error condition.

exception scope: Block of code where exceptions are handled.

finalization code: See epilogue code.

general cancelability: If enabled, allows a thread to receive a cancelation request at specific cancelation points. If disabled, the thread cannot be canceled. See also asynchronous cancelability.

global lock: Single recursive mutex provided by the Threads Library for use by all threads in a process when calling routines or code that is not thread-safe to ensure serialized, exclusive access to the unsafe code.

granularity: Smallest unit of storage (that is, bytes, words, longwords, or quadwords) that a computer can load or store in one machine instruction. See also actual granularity, natural granularity, and system granularity.

guard area: Area at the overflow end of a thread's writable stack and the stack overflow warning area that is inaccessible to the thread. If the thread attempts to access a memory location within the guard area, a memory addressing violation occurs. See also overflow warning area.

guard pages: Low-level memory regions that form a stack guard region.

guardsize attribute: Attribute of a thread that specifies the minimum size (in bytes) of the guard area for a thread's stack.

handle: Storage, similar to a pointer, that refers to a specific Threads Library object.

inherit scheduling attribute: Attribute of a thread that specifies whether a newly created thread inherits the scheduling attributes (scheduling priority, policy and contention scope) of the creating thread or uses the scheduling attributes stored in the attributes object. See also thread attributes object.

kernel execution context: Entity managed by the operating system kernel that uses processing resources. Also known as a kernel thread or virtual processor.

lifetime: Length of time memory is allocated for a particular purpose.

lock acquisition: Each instance of acquiring a mutex or read-write lock.

multithreaded programming: Division of a program into multiple threads that execute concurrently.

mutex: Mutual exclusion, an object that multiple threads use to ensure the integrity of a shared resource that they access (most commonly shared data) by allowing only one thread to access it at a time. See also normal mutex, errorcheck mutex, and recursive mutex.

mutex attributes object: Object that allows you to specify values for mutex attributes when you create a mutex.

mutex kind attribute: Mutex attribute that specifies whether its kind is normal, recursive, or errorcheck.

natural granularity: Granularity of a processor; determined by the processor's architecture, cache architecture, and instruction set. See also actual granularity, granularity, and system granularity.

nonterminating signal: Signal that does not result in the termination of the process by default. See also terminating signal.

normal mutex: A kind of mutex that can be locked exactly once by a thread. It does not perform error checks. If a thread tries to lock the mutex again without first unlocking it, the thread waits for itself to release the lock and deadlocks. In the Threads Library, this kind of mutex offers the best performance. See also mutex, errorcheck mutex, and recursive mutex.

overflow warning area: Area between the overflow end of the thread's writable stack and the stack guard area. If the thread attempts to access a memory location within the overflow warning area, a stack overflow exception occurs. The program can catch this exception and continue processing. See also guard area.

per-thread context: See thread-specific data.

predicate: Boolean expression that defines a particular state of shared data; threads wait on a condition variable for shared data to enter the defined state. See also condition variable.

priority inversion: Occurs when interaction among three or more threads blocks the highest-priority thread from executing until after the lowest-priority thread can execute.

process contention scope: Setting for the contention scope attribute of a thread. Specifies that a thread competes for processing resources only with other threads in the same process. See also contention scope and system contention scope.

race condition: Occurs when two or more threads perform an operation, and the result of the operation depends on unpredictable timing factors.

read-write lock: An object that serializes access, in a thread-safe manner, to a data object that is shared among threads and that is frequently read but less frequently written.

recursive mutex: Mutex that can be locked more than once by a given thread without causing a deadlock. The thread must call the pthread_mutex_unlock() routine the same number of times that it called the pthread_mutex_lock() routine before another thread can lock the mutex. See also deadlock, mutex, normal mutex, and errorcheck mutex.

reentrant: Refers to a routine that functions normally despite being called simultaneously or sequentially in different threads.

scheduling policy attribute: Attribute of a thread that describes how the thread is scheduled for execution relative to the other threads in the program. See also thread attributes object.

scheduling precedence: The set of characteristics of threads and the Threads Library scheduling algorithm that, in combination, determine which thread will be allowed to run when a scheduling decision is made. Scheduling decisions are made either when a thread becomes ready to run (for example, when a mutex on which it was waiting is unlocked, or a condition variable on which it was waiting is signaled or broadcast), or when a thread is blocked (for example, when it attempts to lock a locked mutex or when it waits on a condition variable).

scheduling priority attribute: Attribute of a thread that specifies the execution priority of a thread, expressed relative to other threads in the same policy. See also thread attributes object.

scope: Areas of a program where code can access memory.

software interrupt handler: A routine that is executed in response to an interrupt generated by the operating system or equivalent support software. For example, an AST service routine handles interrupts on OpenVMS systems; a signal handler routine handles interrupts on Tru64 UNIX systems.

stack memory: Memory that is allocated from a thread's stack area at run time by code generated by the language compiler, generally when a routine is initially called. See also dynamic memory and static memory.

stacksize attribute: Attribute of a thread that specifies the minimum size (in bytes) of the memory required for its stack.

start routine: Routine in your program where a newly created thread begins executing.

static memory: Any variable that is permanently allocated at a particular address for the life of the program. See also dynamic memory and stack memory.

status exception: An exception whose identity is based on the status value it contains. See also exception and address exception.

synchronous signal: Signal that is the result of an event that occurs inside a process and is delivered synchronously with respect to that event. See also asynchronous signal.

system contention scope: Setting for the contention scope attribute of a thread. Specifies that a thread competes for processing resources with all other threads in the system. See also contention scope and process contention scope.

system granularity: Granularity provided by an operating system's run-time libraries, to provide a consistent and coherent environment for applications. See also actual granularity, granularity, and natural granularity.

terminating signal: Signal that results in the termination of the process by default. See also nonterminating signal.

thread: Single, sequential flow of control within a program. Within a single thread, there is a single point of execution.