HP OpenVMS Systems Documentation

Delays a thread's 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 interval of time. This interval ends at the current time plus the specified interval. The routine will not return before the end of the interval is reached, but may return an arbitrary amount of time after the end of the interval is reached. 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 either to give up the processor or to deliver a pending cancelation request.

The timespec structure contains the following two fields:

• tv_sec is an integral number of seconds.
• tv_nsec is an integral 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

This routine marks the specified thread object to indicate that storage for the corresponding 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.

You can create a thread already detached by setting its thread object's detachstate attribute.

The pthread_join() routine also detaches the target thread after pthread_join() returns successfully.

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

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.

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

Syntax

pthread_exc_get_status_np(
exception ,
code );

Argument	Data Type	Access
exception	EXCEPTION	read
code	unsigned long	write

int
pthread_exc_get_status_np (
EXCEPTION *exception,
unsigned long *code);

Arguments

exception

Threads Library status exception object whose status code is obtained.

code

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

Description

This routine obtains and returns the system-specific status value from the 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 Threads Library status exceptions, use this routine within a CATCH or CATCH_ALL 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 the Threads Library.

Associated Routines

pthread_exc_set_status_np()

(Macro) Determines whether two Threads Library exception objects are identical.

Syntax

pthread_exc_matches_np(
exception1 ,
exception2 );

Argument	Data Type	Access
exception1	EXCEPTION	read
exception2	EXCEPTION	read

int
pthread_exc_matches_np (
EXCEPTION *exception1,
EXCEPTION *exception2);

Arguments

exception1

Threads Library exception object.

exception2

Threads Library exception object.

Description

This routine compares two 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 exception objects specified in the arguments exception1 and exception2 are identical.

Associated Routines

pthread_exc_get_status_np()
pthread_exc_report_np()
pthread_exc_set_status_np()

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

Syntax

pthread_exc_report_np(
exception );

Argument	Data Type	Access
exception	EXCEPTION	read

void
pthread_exc_report_np (
EXCEPTION *exception);

Arguments

exception

Threads Library exception object that has been set with a status value.

Description

This routine produces a text message on the stderr device (Tru64 UNIX 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 status exceptions, use this routine within a CATCH or CATCH_ALL code block to produce the message associated with a caught exception. Note that any exception objects set to the same status value are considered equivalent by the Threads Library.

Associated Routines

pthread_exc_get_status_np()
pthread_exc_set_status_np()

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

Syntax

pthread_exc_set_status_np(
exception ,
code );

Argument	Data Type	Access
exception	EXCEPTION	write
code	unsigned long	read

void
pthread_exc_set_status_np (
EXCEPTION *exception,
unsigned long code);

Arguments

exception

Threads Library 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 address exception object. This transforms the address exception object into a status exception object.

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

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

Associated Routines

pthread_exc_get_status_np()

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. The Threads Library 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 are 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.

The Threads Library issues an implicit call to pthread_exit() when a thread returns from the start routine that was used to create it. The Threads Library 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, do not use references to local variables of the existing thread for the value_ptr argument of the pthread_exit() routine.

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(
);

int
pthread_getconcurrency (
void);

Description

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

The concurrency level value has no effect on the behavior of a multithreaded program that uses the Threads Library. 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 the Threads Library controls the concurrency level.

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

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

int
pthread_getname_np (
pthread_thread_t thread,
char *name,
size_t len);

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. 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.

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

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() routine for valid policies and their meanings.

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 either 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.

Associated Routines

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