Guide to DECthreads

pthreadDbgStatus_t
pthread_debug_cmd (
char *cmd);

ARGUMENTS

cmd

pthread_debug() command string to pass to DECthreads debug. Null-terminated string, commands separated by semicolons.

DESCRIPTION

This routine passes a list of debugging commands to DECthreads. Each command (separated by a semicolon) is executed in sequence. Any output is written to standard output. This routine returns the status of the last specified operation in the command string when the final command (or Exit command) is executed.

For a list of pthread_debug() commands, see Appendix D.

The following are two examples of listing commands in a call to this routine:

   pthread_debug_cmd("thread -b; mu -lq; cond -wq"); 
   pthread_debug_cmd("att"); 

To invoke the DECthreads debugger for interactive commands, call pthread_debug().

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return	Description
0	Command successful
[PTHREAD_DBG_QUIT] (1)	Last command was quit or exit
[PTHREAD_DBG_NONESEL] (2)	No objects selected (for example, thread -br)
[PTHREAD_DBG_SUCCESSPEND] (3)	Alternate success
[PTHREAD_DBG_NOPRIV] (--1)	No privilege for command
[PTHREAD_DBG_INVPARAM] (--2)	Invalid parameter on command
[PTHREAD_DBG_INVSEQ] (--3)	Invalid object sequence number given
[PTHREAD_DBG_INCONSTATE] (--4)	Inconsistent state for operation
[PTHREAD_DBG_CORRUPT] (--5)	Unable to complete due to internal corruption
[PTHREAD_DBG_INVOPTION] (--6)	Invalid command options
[PTHREAD_DBG_NOARG] (--7)	Missing command argument
[PTHREAD_DBG_INVADDR] (--8)	Invalid address
[PTHREAD_DBG_INVCMD] (--9)	Invalid command
[PTHREAD_DBG_NULLCMD] (--10)	No command given
[PTHREAD_DBG_CONFLICT] (--11)	Conflicting options
[PTHREAD_DBG_UNIMPL] (--12)	Unimplemented feature

Associated Routines

• pthread_debug()

Causes a thread to delay execution.

Syntax

pthread_delay_np(
interval );

Argument	Data Type	Access
interval	struct timespec	read

int
pthread_delay_np (
const struct timespec *interval);

ARGUMENTS

interval

Number of seconds and nanoseconds to delay execution. The value specified for each must be greater than or equal to zero.

DESCRIPTION

This routine causes a thread to delay execution for a specific period of time. This period ends at the current time plus the specified interval. The routine will not return before the end of the period is reached, but may return an arbitrary amount of time after the period has gone by. This can be due to system load, thread priorities, and system timer granularity.

Specifying an interval of zero (0) seconds and zero (0) nanoseconds is allowed and can be used to force the thread to give up the processor or to deliver a pending cancelation request.

The timespec structure contains the following two fields:

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

Marks a thread object for deletion.

Syntax

pthread_detach(
thread );

Argument	Data Type	Access
thread	opaque pthread_t	read

int
pthread_detach (
pthread_t thread);

ARGUMENTS

thread

Thread object being marked for deletion.

DESCRIPTION

A call to this routine indicates that storage for the specified thread can be reclaimed when the thread terminates. This includes storage for the thread argument's return value, as well as the thread object. If thread has not terminated when this routine is called, this routine does not cause it to terminate.

When a thread object is no longer referenced, call this routine.

The results of this routine are unpredictable if the value of thread refers to a thread object that does not exist.

A thread can be created "pre-detached" using its thread object's detach state attribute. The pthread_join() function also detaches the target thread when pthread_join() returns successfully.

Associated Routines

• pthread_cancel()
• pthread_create()
• pthread_exit()
• pthread_join()

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

int
pthread_equal (
pthread_t t1,
pthread_t t2);

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.

Terminates the calling thread.

Syntax

pthread_exit(
value _ptr );

Argument	Data Type	Access
value_ptr	void *	read

void
pthread_exit (
void *value_ptr);

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.

Associated Routines

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

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

int
pthread_get_expiration_np (
const struct timespec *delta,
struct timespec *abstime);

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 integer number of seconds.
• tv.nsec is an integer number of nanoseconds.

Associated Routines

• pthread_cond_timedwait()

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

int
pthread_getschedparam (
pthread_t thread,
int *policy,
struct sched_param *param);

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() function 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() function for valid values.

DESCRIPTION

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

The priority value returned in the param structure is the value specified in attr at pthread_create() or by the most recent pthread_setschedparam() call affecting 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.

Associated Routines

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

Obtains the thread sequence number.

Syntax

pthread_getsequence_np(
thread );

Argument	Data Type	Access
thread	opaque pthread_t	read

unsigned long
pthread_getsequence_np (
pthread_t thread);

ARGUMENTS

thread

Thread whose sequence number is obtained.

DESCRIPTION

This routine obtains the sequence number of the specified thread, which provides a unique identifier for each concurrent thread. Thread sequence numbers are never reused while a thread exists, but may be reused after the thread terminates. The debugger interfaces use this sequence number to identify each thread in commands and in display output.

Associated Routines

• pthread_create()

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

Syntax

pthread_getspecific(
key );

Argument	Data Type	Access
key	opaque pthread_key_t	read

void
*pthread_getspecific (
pthread_key_t key);

ARGUMENTS

key

Context key identifies the thread-specific data to be obtained. This key must be obtained from pthread_key_create().

DESCRIPTION

This routine obtains the thread-specific data associated with the specified key for the current thread. This function 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.

Associated Routines

• pthread_key_create()
• pthread_setspecific()

---

pthread_join32(), pthread_join64()

The pthread_join32() and pthread_join64() forms are only valid in 64-pointer environments for OpenVMS Alpha. For information regarding 32- and 64-bit pointers, see Appendix B. Ensure that your compiler provides 64-bit support prior to using pthread_join64().

---

Causes the calling thread to wait for the termination of a specified thread.

Syntax

pthread_join(
thread ,
value _ptr );

Argument	Data Type	Access
thread	opaque pthread_t	read
value_ptr	void *	write

int
pthread_join (
pthread_t thread,
void **value_ptr);

ARGUMENTS

thread

Thread whose termination is awaited by the caller of this routine.

value_ptr

Return value of the terminating thread (when that thread calls pthread_exit() or returns.)

DESCRIPTION

This routine suspends execution of the calling thread until the specified target thread thread terminates.

A call to a pthread_join() routine returns after the target thread terminates. The pthread_join() routine is a deferred cancelation point: the target thread will not be detached if the thread blocked in pthread_join() is canceled.

On return from a successful pthread_join() call with a non-NULL value_ptr argument, the value passed to pthread_exit() is returned in the location referenced by value_ptr, and the terminating thread is detached. If more than one thread attempts to join with a single thread, the results are unpredictable.

If a thread calls this routine and specifies its own pthread_t, a deadlock can result.

The pthread_join() (or pthread_detach()) function should eventually be called for every thread that is created with the detachstate attribute of its thread object set to PTHREAD_CREATE_JOINABLE, so that storage associated with the thread may be reclaimed.

For OpenVMS Alpha systems only, you can call pthread_join32() or pthread_join64() instead of pthread_join(). The pthread_join32() form returns a 32-bit void * value in the address to which value_ptr points. The pthread_join64() form returns a 64-bit void * value. You can call either, or you can call pthread_join(). The pthread_join() routine is defined to pthread_join64() if you compile using /pointer_size=long. If you do not specify /pointer_size, or if you specify /pointer_size=short, then pthread_join() is defined to be pthread_join32().

Associated Routines

• pthread_cancel()
• pthread_create()
• pthread_detach()
• pthread_exit()

Generates a unique thread-specific data key.

Syntax

pthread_key_create(
key ,
destructor );

Argument	Data Type	Access
key	opaque pthread_key_t	write
destructor	procedure	read

int
pthread_key_create (
pthread_key_t *key,
void (*destructor)(void *));

ARGUMENTS

key

The new thread-specific data key.

destructor

Procedure called to destroy a thread-specific data value associated with the created key when the thread terminates. Note, the argument to the destructor for the user-specified routine is the non-NULL value associated with a key.

DESCRIPTION

This routine generates a unique, thread-specific data key that is visible to all threads in the process. The variable key provided by this routine is an opaque object used to locate thread-specific data. Although the same key value may be used by different threads, the values bound to the key by pthread_setspecific() are maintained on a per-thread basis and persist for the life of the calling thread.

DECthreads imposes a maximum number of thread-specific data keys, equal to the symbolic constant PTHREAD_KEYS_MAX.

Thread-specific data allows client software to associate "static" information with the current thread. For example, where a routine declares a variable "static" in a single-threaded program, a multithreaded version of the program might create a thread-specific data key to store the same variable.

This routine generates and returns a new key value. The key reserves a cell within each thread. Each call to this routine creates a new cell that is unique within an application invocation. Keys must be generated from initialization code that is guaranteed to be called only once within each process. (See the pthread_once() description for more information.)

When a thread terminates, its thread-specific data is automatically destroyed; however, the key remains unless destroyed by a call to pthread_key_delete(). An optional destructor function may be associated with each key. At thread exit, if a key has a non-NULL destructor pointer, and the thread has a non-NULL value associated with that key, the destructor function is called with the current associated value as its sole argument. The order in which thread-specific data destructors are called at thread termination is undefined.

Before each destructor is called, the thread's value for the corresponding key is set to NULL. After the destructors have been called for all non-NULL values with associated destructors, if there are still some non-NULL values with associated destructors, then the process is repeated. If there are still non-NULL values for any key with a destructor after four repetitions of this process, DECthreads will terminate the thread. At this point, any key values that represent allocated heap will be lost. Note that this occurs only when a destructor performs some action that creates a new value for some key. Destructor code should attempt to avoid this sort of circularity.

Associated Routines

• pthread_getspecific()
• pthread_setspecific()
• pthread_key_delete()
• pthread_once()

Deletes a thread-specific data key.

Syntax

pthread_key_delete(
key );

Argument	Data Type	Access
key	opaque pthread_key_t	write

  6493P010.HTM
  OSSG Documentation
  22-NOV-1996 13:20:11.06

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal