HP OpenVMS Systems Documentation

Wakes one thread that is waiting on the specified condition variable (called from interrupt level only).

Syntax

pthread_cond_sig_preempt_int_np (cond)

Argument	Data Type	Access
cond	opaque pthread_cond_t	read

Arguments

cond

Condition variable signaled.

Description

This routine wakes one thread waiting on a condition variable. It can only be called from a software interrupt handler routine. Calling this routine implies that it might be possible for a single waiting thread to proceed. Call this routine when any thread waiting on the specified condition variable might find its predicate true.

The scheduling policies of the waiting threads determine which thread is awakened. For policies SCHED_FIFO and SCHED_RR , a blocked thread is chosen in priority order, using first-in/first-out (FIFO) within priorities.

You can call this routine when the associated mutex is either locked or unlocked. (Never try to lock a mutex from an interrupt handler.)

This routine allows you to signal a thread from a software interrupt handler. Do not call this routine from noninterrupt code. If you want to signal a thread from the normal noninterrupt level, use pthread_cond_signal .

Note If a waiting thread has a preemptive scheduling policy and a higher priority than the thread which was running when the interrupt occurred, then the waiting thread will preempt the interrupt routine and begin to run immediately. This is unlike pthread_cond_signal_int_np() which causes the condition variable to be signaled at a safe point after the interrupt has completed. pthread_cond_sig_preempt_int_np() avoids the possible latency which pthread_cond_signal_int_np() may introduce; however, a side effect of this is that during the call to pthread_cond_sig_preempt_int_np() other threads may run if a preemption occurs. Thus, once an interrupt routine calls pthread_cond_sig_preempt_int_np() it can no longer rely on any assumptions of exclusivity or atomicity which are typically provided by interrupt routines. Furthermore, once the call to pthread_cond_sig_preempt_int_np() is made, in addition to other threads running, subsequent interrupts may be delivered at any time as well (that is, they will not be blocked until the current interrupt completes). For this reason, it is recommended that pthread_cond_sig_preempt_int_np() be called as the last statement in the interrupt routine.

Associated Routines

pthread_cond_broadcast()
pthread_cond_signal()
pthread_cond_signal_int_np()
pthread_cond_timedwait()
pthread_cond_wait()

Causes a thread to wait for the specified condition variable to be signaled or broadcast, 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

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

Description

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

• The specified condition variable is signaled or broadcast.
• 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 broadcast, 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. When the thread regains control after calling pthread_cond_timedwait() , the mutex is locked and the thread is the owner. This is true regardless of why the wait ended. If general cancelability is enabled, the thread reacquires the mutex (blocking for it if necessary) before the cleanup handlers are run (or before the exception is raised).

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 have locked the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex. The only routines that are supported for use with asynchronous cancelability enabled are those that disable asynchronous cancelability.

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

Syntax

pthread_cond_wait(
cond ,
mutex );

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

int
pthread_cond_wait (
pthread_cond_t *cond,
pthread_mutex_t *mutex);

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 broadcast. 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. When the thread regains control after calling pthread_cond_wait() , the mutex is locked and the thread is the owner. This is true regardless of why the wait ended. If general cancelability is enabled, the thread reacquires the mutex (blocking for it if necessary) before the cleanup handlers are run (or before the exception is raised).

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

The only routines that are supported for use with asynchronous cancelability enabled are those that disable asynchronous cancelability.

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

int
pthread_create (
pthread_t *thread,
const pthread_attr_t *attr,
void * (*start_routine) (void *),
void *arg);

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:

• The Threads Library 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 Tru64 UNIX, or the pthread.h header file on other 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

The Threads Library 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, condition variables or read-write locks.

For the duration of the new thread's existence, the Threads Library 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).

The Threads Library assigns each new thread a thread identifier, which is written into the address specified as the pthread_create() routine's thread argument. The new thread's thread identifier is written 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 Tru64 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, the following actions are performed:

1. A return value (if one is available) is written into the terminated thread's thread object, as follows:
   • If the thread has been canceled, the value PTHREAD_CANCELED is written into the thread's thread object.
   • If the thread terminated by returning from its start routine, the return value is copied from the start routine (if one is available) into the thread's thread object. Alternatively, if the thread explicitly called pthread_exit() , the value received in the value_ptr argument (from pthread_exit() ) is stored in 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() , the Threads Library calls, in turn, each cleanup handler that this thread declared (using pthread_cleanup_push() ) and that is not yet removed (using pthread_cleanup_pop() ). (The Threads Library also transfers control to any appropriate CATCH , CATCH_ALL , or FINALLY blocks , as described in Chapter 5 .)
   The Threads Library 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() , the Threads Library raises the pthread_exit_e exception. To exit the terminated thread due to cancelation, the Threads Library raises the pthread_cancel_e exception.
   Your program can use the 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 exception package.
4. For each of the terminated thread's thread-specific data keys that has a non-NULL value:
   • The thread's value for the corresponding key is set to NULL.
   • Call each thread-specific data destructor function in this multithreaded process' list of destructors.
   
   Repeat 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. Awaken the thread (if there is one) that is currently waiting to join with the terminated thread. That is, awaken the thread that is waiting in a call to pthread_join() .
6. If the thread is already detached, destroy its thread object. Otherwise, the thread continues to exist until detached or joined with. Section 2.3.4 describes detaching and destroying a thread.

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