HP OpenVMS Systems Documentation

Causes a thread to wait for the specified condition variable to be signaled or broadcasted, such that it will awake after a specified period of time.

Syntax

pthread_cond_timedwait(
cond ,
mutex ,
abstime );

Argument	Data Type	Access
cond	opaque pthread_cond_t	modify
mutex	opaque pthread_mutex_t	modify
abstime	structure timespec	read

C Binding

Arguments

cond

Condition variable that the calling thread waits on.

mutex

Mutex associated with the condition variable specified in cond.

abstime

Absolute time at which the wait expires, if the condition has not been signaled or broadcasted. See the pthread_get_expiration_np() routine, which is used to obtain a value for this argument.

The abstime argument is specified in Universal Coordinated Time (UTC). In the UTC-based model, time is represented as seconds since the Epoch. The Epoch is defined as the time 0 hours, 0 minutes, 0 seconds, January 1st, 1970 UTC. Seconds since the Epoch is a value interpreted as the number of seconds between a specified time and the Epoch.

Description

This routine causes a thread to wait until one of the following occurs:

• The specified condition variable is signaled or broadcasted.
• The current system clock time is greater than or equal to the time specified by the abstime argument.

This routine is identical to pthread_cond_wait(), except that this routine can return before a condition variable is signaled or broadcasted; specifically, when the specified time expires. For more information, see the pthread_cond_wait() description.

This routine atomically releases the mutex and causes the calling thread to wait on the condition. The atomicity is important, because it means the thread cannot miss a wakeup while the mutex is unlocked. When the timer expires or when the wait is satisfied as a result of some thread calling pthread_cond_signal() or pthread_cond_broadcast(), the mutex is reacquired before returning to the caller.

If the current time equals or exceeds the expiration time, this routine returns immediately, releasing and reacquiring the mutex. It might cause the calling thread to yield (see the sched_yield() description. Your code should check the return status whenever this routine returns and take the appropriate action. Otherwise, waiting on the condition variable can become a nonblocking loop.

Call this routine after you lock the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex.

Return Values

Associated Routines

• pthread_cond_broadcast()
• pthread_cond_destroy()
• pthread_cond_init()
• pthread_cond_signal()
• pthread_cond_wait()
• pthread_get_expiration_np()

Causes a thread to wait for the specified condition variable to be signaled or broadcasted.

Syntax

pthread_cond_wait(
cond ,
mutex );

Argument	Data Type	Access
cond	opaque pthread_cond_t	modify
mutex	opaque pthread_mutex_t	modify

C Binding

Arguments

cond

Condition variable that the calling thread waits on.

mutex

Mutex associated with the condition variable specified in cond.

Description

This routine causes a thread to wait for the specified condition variable to be signaled or broadcasted. Each condition corresponds to one or more Boolean relations, called a predicate, based on shared data. The calling thread waits for the data to reach a particular state for the predicate to become true. However, the return from this routine does not imply anything about the value of the predicate and it should be reevaluated upon return. Condition variables are discussed in Chapter 2 and Chapter 3.

Call this routine after you have locked the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex.

This routine atomically releases the mutex and causes the calling thread to wait on the condition. The atomicity is important, because it means the thread cannot miss a wakeup while the mutex is unlocked. When the wait is satisfied as a result of some thread calling pthread_cond_signal() or pthread_cond_broadcast(), the mutex is reacquired before returning to the caller.

A thread that changes the state of storage protected by the mutex in such a way that a predicate associated with a condition variable might now be true, must call either pthread_cond_signal() or pthread_cond_broadcast() for that condition variable. If neither call is made, any thread waiting on the condition variable continues to wait.

This routine might (with low probability) return when the condition variable has not been signaled or broadcasted. When this occurs, the mutex is reacquired before the routine returns. To handle this type of situation, enclose each call to this routine in a loop that checks the predicate. The loop provides documentation of your intent and protects against these spurious wakeups, while also allowing correct behavior even if another thread consumes the desired state before the awakened thread runs.

It is illegal for threads to wait on the same condition variable by specifying different mutexes.

Return Values

Associated Routines

• pthread_cond_broadcast()
• pthread_cond_destroy()
• pthread_cond_init()
• pthread_cond_signal()
• pthread_cond_timedwait()

Creates a thread.

Syntax

pthread_create(
thread ,
attr ,
start _routine,
arg );

Argument	Data Type	Access
thread	opaque pthread_t	write
attr	opaque pthread_attr_t	read
start_routine	procedure	read
arg	user_arg	read

C Binding

Arguments

thread

Location for thread object to be created.

attr

Thread attributes object that defines the characteristics of the thread being created. If you specify NULL, default attributes are used.

start_routine

Function executed as the new thread's start routine.

arg

Address value copied and passed to the thread's start routine.

Description

This routine creates a thread. A thread is a single, sequential flow of control within a program. It is the active execution of a designated routine, including any nested routine invocations.

Successful execution of this routine includes the following actions:

• DECthreads creates a thread object to describe and control the thread. The thread object includes a thread environment block (TEB) that programs can use, with care. (See the <sys/types.h> header file on DIGITAL UNIX, or the pthread.h header file on other DECthreads platforms.)
• The thread argument receives an identifier for the new thread.
• An executable thread is created with attributes specified by the attr argument (or with default attributes if NULL is specified).

Thread Creation

DECthreads creates a thread in the ready state and prepares the thread to begin executing its start routine, the function passed to pthread_create() as the start_routine argument. Depending on the presence of other threads and their scheduling and priority attributes, the new thread might start executing immediately. The new thread can also preempt its creator, depending on the two threads' respective scheduling and priority attributes. The caller of pthread_create() can synchronize with the new thread using the pthread_join() routine or using any mutually agreed upon mutexes or condition variables.

For the duration of the new thread's existence, DECthreads maintains and manages the thread object and other thread state overhead. A thread exists until it is both terminated and detached. A thread is detached when created if the detachstate attribute of its thread object is set to PTHREAD_CREATE_DETACHED. It is also detached after any thread returns successfully from calling pthread_detach() or pthread_join() for the thread. Termination is explained in the next section (see Thread Termination).

DECthreads assigns each new thread a thread identifier, which DECthreads writes into the address specified as the pthread_create() routine's thread argument. DECthreads writes the new thread's thread identifier before the new thread executes.

By default, the new thread's scheduling policy and priority are inherited from the creating thread---that is, by default, the pthread_create() routine ignores the scheduling policy and priority set in the specified thread attributes object. Thus, to create a thread that is subject to the scheduling policy and priority set in the specified thread attributes object, before calling pthread_create() your program must use the pthread_attr_setinheritsched() routine to set the inherit thread attributes object's scheduling attribute to PTHREAD_EXPLICIT_SCHED.

On DIGITAL UNIX, the signal state of the new thread is initialized as follows:

1. The signal mask is inherited from the creating thread.
2. The set of signals pending for the new thread is empty.

If pthread_create() fails, no new thread is created, and the contents of the location referenced by thread are undefined.

Thread Termination

A thread terminates when one of the following events occurs:

• The thread returns from its start routine.
• The thread calls the pthread_exit() routine.
• The thread is canceled.

When a thread terminates, DECthreads performs these actions:

1. DECthreads writes a return value (if one is available) into the terminated thread's thread object, as follows:
   • If the thread has been canceled, DECthreads writes the value PTHREAD_CANCELED into the thread's thread object.
   • If the thread terminated by returning from its start routine, DECthreads copies the return value from the start routine (if one is available) into the thread's thread object. Alternatively, if the thread explictly called pthread_exit(), DECthreads stores the value received in the value_ptr argument (from pthread_exit()) into the thread's thread object.
   
   Another thread can obtain this return value by joining with the terminated thread (using pthread_join()). See Section 2.3.5 for a description of joining with a thread.

   Note If the thread terminated by returning from its start routine normally and the start routine does not provide a return value, the results obtained by joining with that thread are unpredictable.

2. If the termination results from a cancelation request or a call to pthread_exit(), DECthreads calls, in turn, each cleanup handler that this thread declared (using pthread_cleanup_push()) and that is not yet removed (using pthread_cleanup_pop()). (DECthreads also transfers control to any appropriate CATCH, CATCH_ALL, or FINALLY blocks , as described in Chapter 5 .)
   DECthreads calls the terminated thread's most recently pushed cleanup handler first. See Section 2.3.3.1 for more information about cleanup handlers.
   For C++ programmers: At normal exit from a thread, your program will call the appropriate destructor functions, just as if an exception had been raised.
3. To exit the terminated thread due to a call to pthread_exit(), DECthreads raises the pthread_exit_e exception. To exit the terminated thread due to cancelation, DECthreads raises the pthread_cancel_e exception.
   Your program can use the DECthreads exception package to operate on the generated exception. (In particular, note that the practice of using CATCH handlers in place of pthread_cleanup_push() is not portable.) Chapter 5 describes the DECthreads exception package.
4. For each of the terminated thread's thread-specific data keys that has a non-NULL value:
   • DECthreads sets the thread's value for the corresponding key to NULL.
   • In turn, DECthreads calls each thread-specific data destructor function in this multithreaded process's list of destructors.
   
   DECthreads repeats this step until all thread-specific data values in the thread are NULL, or for up to a number of iterations equal to PTHREAD_DESTRUCTOR_ITERATIONS. This destroys all thread-specific data associated with the terminated thread. See Section 2.6 for more information about thread-specific data.
5. DECthreads awakens the thread (if there is one) that is currently waiting to join with the terminated thread. That is, DECthreads awakens the thread that is waiting in a call to pthread_join().
6. If the thread is already detached, DECthreads destroys its thread object. Otherwise, the thread continues to exist until detached or joined with. Section 2.3.4 describes detaching and destroying a thread.

Return Values

Associated Routines

• pthread_atfork()
• pthread_attr_destroy()
• pthread_attr_init()
• pthread_attr_setdetachstate()
• pthread_attr_setinheritsched()
• pthread_attr_setschedparam()
• pthread_attr_setschedpolicy()
• pthread_attr_setstacksize()
• pthread_cancel()
• pthread_detach()
• pthread_exit()
• pthread_join()

Delays a thread's execution.

Syntax

pthread_delay_np(
interval );

Argument	Data Type	Access
interval	struct timespec	read

C Binding

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

Return Values

Marks a thread object for deletion.

Syntax

pthread_detach(
thread );

Argument	Data Type	Access
thread	opaque pthread_t	read

C Binding

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.

A thread can be created 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

Associated Routines

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