Updated: 11 December 1998

Guide to DECthreads

Compares one thread identifier to another thread identifier.

Syntax

pthread_equal(
t1 ,
t2 );

Argument	Data Type	Access
t1	opaque pthread_t	read
t2	opaque pthread_t	read

C Binding

Arguments

t1

The first thread identifier to be compared.

t2

The second thread identifier to be compared.

Description

This routine compares one thread identifier to another thread identifier.

If either t1 or t2 are not valid thread identifiers, this routine's behavior is undefined.

Return Values

(Macro) Obtains a system-defined error status from a DECthreads status exception object.

Syntax

pthread_exc_get_status_np(
exception ,
code );

Argument	Data Type	Access
exception	EXCEPTION	read
code	unsigned long	write

C Binding

Arguments

exception

DECthreads status exception object whose status code is obtained.

code

Receives the system-specific status code associated with the specified DECthreads status exception object.

Description

This routine obtains and returns the system-specific status value from the DECthreads status exception object specified in the exception argument. This value must have already been associated with the exception object using the pthread_exc_set_status_np() routine.

In a program that uses DECthreads status exceptions, use this routine within a CATCH, CATCH_ALL, or FINALLY code block to obtain the status code value associated with a caught exception. Note that any exception objects set to the same status value are considered equivalent by DECthreads.

Return Values

Associated Routines

• pthread_exc_set_status_np()

(Macro) Determines whether two DECthreads exception objects are identical.

Syntax

pthread_exc_matches_np(
exception1 ,
exception2 );

Argument	Data Type	Access
exception1	EXCEPTION	read
exception2	EXCEPTION	read

C Binding

Arguments

exception1

DECthreads exception object.

exception2

DECthreads exception object.

Description

This routine compares two DECthreads exception objects, taking into consideration whether each is an address exception or status exception.

This routine returns either the C language value TRUE or the C language value FALSE, indicating whether the two DECthreads exception objects specified in the arguments exception1 and exception2 are identical.

Return Values

Associated Routines

• pthread_exc_get_status_np()
• pthread_exc_report_np()
• pthread_exc_set_status_np()

Produces a message that reports what a specified DECthreads status exception object represents.

Syntax

pthread_exc_report_np(
exception );

Argument	Data Type	Access
exception	EXCEPTION	read

C Binding

Arguments

exception

DECthreads exception object that has been set with a status value.

Description

This routine produces a text message on the stderr device (Digital UNIX and Windows NT systems) or SYS$ERROR device (OpenVMS systems) that describes the exception whose exception object is specified in the exception argument.

In a program that uses DECthreads status exceptions, use this routine within a CATCH, CATCH_ALL, or FINALLY code block to obtain the status code value associated with a caught exception. Note that any exception objects set to the same status value are considered equivalent by DECthreads.

Return Values

Associated Routines

• pthread_exc_get_status_np()
• pthread_exc_set_status_np()

(Macro) Imports a system-defined error status into a DECthreads address exception object.

Syntax

pthread_exc_set_status_np(
exception ,
code );

Argument	Data Type	Access
exception	EXCEPTION	write
code	unsigned long	read

C Binding

Arguments

exception

DECthreads address exception object into which the specified status code is imported.

code

System-specific status code to be imported.

Description

This routine associates a system-specific status value with the specified DECthreads address exception object. This transforms the address exception object into a DECthreads status exception object.

The exception argument must already have been initialized with the DECthreads exception package's EXCEPTION_INIT macro.

Use this routine to associate any system-specific status value with the specified DECthreads address exception object. Note that any exception objects set to the same status value are considered equivalent by DECthreads.

Return Values

Associated Routines

• pthread_exc_get_status_np()

Terminates the calling thread.

Syntax

pthread_exit(
value _ptr );

Argument	Data Type	Access
value_ptr	void *	read

C Binding

Arguments

value_ptr

Value copied and returned to the caller of pthread_join(). Note that void * is used as a universal datatype, not as a pointer. DECthreads treats the value_ptr as a value and stores it to be returned by pthread_join().

Description

This routine terminates the calling thread and makes a status value (value_ptr) available to any thread that calls pthread_join() and specifies the terminating thread.

Any cleanup handlers that have been pushed and not yet popped from the stack, are popped in the reverse order that they were pushed and then executed. After all cleanup handlers have been executed, appropriate destructor functions shall be called in an unspecified order if the thread has any thread-specific data. Thread termination does not release any application-visible process resources, including, but not limited to mutexes and file descriptors, nor does it perform any process-level cleanup actions, including, but not limited to calling any atexit() routine that may exist.

An implicit call to pthread_exit() is issued when a thread returns from the start routine that was used to create it. DECthreads writes the function's return value as the return value in the thread's thread object. The process exits when the last running thread calls pthread_exit().

After a thread has terminated, the result of access to local (that is, explicitly or implicitly declared auto) variables of the thread is undefined. So, references to local variables of the existing thread should not be used for the value_ptr argument of the pthread_exit() routine.

Return Values

Associated Routines

• pthread_cancel()
• pthread_create()
• pthread_detach()
• pthread_join()

Obtains the value of the concurrency level global variable for this process.

Syntax

pthread_getconcurrency(
);

C Binding

Description

This routine obtains and returns the value of the "concurrency level" global setting for the calling thread's process. Because DECthreads automatically manages the concurrency of all threads in a multithreaded process, DECthreads ignores this concurrency level value.

The concurrency level value has no effect on the behavior of a multithreaded program that uses DECthreads. This routine is provided for Single UNIX Specification, Version 2, source code compatibility and has no other effect when called.

The initial concurrency level is zero (0), indicating that DECthreads controls the concurrency level.

The concurrency level can be set using the pthread_setconcurrency() routine.

Return Values

Associated Routines

• pthread_setconcurrency()

Obtains the object name from the thread object for an existing thread.

Syntax

pthread_getname_np(
thread ,
name ,
len );

Argument	Data Type	Access
thread	opaque pthread_thread_t	read
name	char	write
len	opaque size_t	read

C Binding

Arguments

thread

Thread object whose object name is to be obtained.

name

Location to store the obtained object name.

len

Length in bytes of buffer at the location specified by name.

Description

This routine copies the object name from the thread object specified by the thread argument to the buffer at the location specified by the name argument. Before calling this routine, your program must allocate the buffer indicated by name.

The object name is a C language string and provides an identifier that is meaningful to a person debugging a multithreaded application based on DECthreads. The maximum number of characters in the object name is 31.

If the specified thread object has not been previously set with an object name, this routine copies a C language null string into the buffer at location name.

Return Values

Associated Routines

• pthread_setname_np()

Obtains the current scheduling policy and scheduling parameters of a thread.

Syntax

pthread_getschedparam(
thread ,
policy ,
param );

Argument	Data Type	Access
thread	opaque pthread_t	read
policy	integer	write
param	struct sched_param	write

C Binding

Arguments

thread

Thread whose scheduling policy and parameters are obtained.

policy

Receives the value of the scheduling policy for the thread specified in thread. Refer to the description of the pthread_setschedparam() routine for valid parameters and their values.

param

Receives the value of the scheduling parameters for the thread specified in thread. Refer to the description of the pthread_setschedparam() routine for valid values.

Description

This routine obtains both the current scheduling policy and associated scheduling parameters of the thread specified by the thread argument.

The priority value returned in the param structure is the value specified in the attr argument passed to pthread_create() or by the most recent call to pthread_setschedparam() that affects the target thread.

This routine differs from pthread_attr_getschedpolicy() and
pthread_attr_getschedparam(), in that those routines get the scheduling policy and parameter attributes that are used to establish the priority and scheduling policy of a new thread when it is created. This routine, however, obtains the scheduling policy and parameters of an existing thread.

Return Values

Associated Routines

• pthread_attr_getschedparam()
• pthread_attr_getschedpolicy()
• pthread_create()
• pthread_self()
• pthread_setschedparam()

Obtains the unique identifier for the specified thread.

Syntax

pthread_getsequence_np(
thread );

Argument	Data Type	Access
thread	opaque pthread_t	read

C Binding

Arguments

thread

Thread whose sequence number is to be obtained.

Description

This routine obtains and returns the DECthreads thread sequence number for the thread identified by the thread object specified in the thread argument.

The thread sequence number provides a unique identifier for each existing thread. A thread's thread sequence number is never reused while the thread exists, but can be reused after the thread terminates. The debugger interfaces use this sequence number to identify each thread in commands and in display output.

The result of calling this routine is undefined if the thread argument does not specify a valid thread object.

Return Values

Associated Routines

• pthread_create()
• pthread_self()

Obtains the thread-specific data associated with the specified key.

Syntax

pthread_getspecific(
key );

Argument	Data Type	Access
key	opaque pthread_key_t	read

C Binding

Arguments

key

The context key identifies the thread-specific data to be obtained. Obtain this key by calling the pthread_key_create() routine.

Description

This routine obtains the thread-specific data associated with the specified key for the current thread. This routine returns the value currently bound to the specified key on behalf of the calling thread.

This routine may be called from a thread-specific data destructor function.

Return Values

Associated Routines

• pthread_key_create()
• pthread_setspecific()

Obtains a value representing a desired expiration time.

Syntax

pthread_get_expiration_np(
delta ,
abstime );

Argument	Data Type	Access
delta	struct timespec	read
abstime	struct timespec	write

C Binding

Arguments

delta

Number of seconds and nanoseconds to add to the current system time. (The result is the time in the future.) This result will be placed in abstime.

abstime

Value representing the absolute expiration time. The absolute expiration time is obtained by adding delta to the current system time. The resulting abstime is in Universal Coordinated Time (UTC). This value should be passed to the pthread_cond_timedwait() routine.

Description

This routine adds a specified interval to the current absolute system time and returns a new absolute time. This new absolute time is used as the expiration time in a call to pthread_cond_timedwait().

The timespec structure contains the following two fields:

• tv_sec is an integral number of seconds.
• tv_nsec is an integral number of nanoseconds.

Return Values

Associated Routines

• pthread_cond_timedwait()

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6101PRO_019.HTML