Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## pthread_cond_sig_preempt_int_np

> 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

C Binding void
pthread_cond_sig_preempt_int_np (
pthread_cond_t *cond);

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

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 | Successful completion.
[EINVAL] | The value specified by cond is not a valid condition variable.

#### Associated Routines

> `pthread_cond_broadcast()`
> `pthread_cond_signal()`
> `pthread_cond_signal_int_np()`
> `pthread_cond_timedwait()`
> `pthread_cond_wait()`

## pthread_cond_timedwait

> 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

C Binding #include <pthread.h>
int
pthread_cond_timedwait (
pthread_cond_t *cond,
pthread_mutex_t *mutex,
const struct timespec *abstime);

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

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

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The value specified by cond, mutex, or abstime is invalid, or Different mutexes are supplied for concurrent `pthread_cond_timedwait()` operations or `pthread_cond_wait()` operations on the same condition variable, or The mutex was not owned by the calling thread at the time of the call.
[ETIMEDOUT] | The time specified by abstime expired.
[ENOMEM] | The Threads Library cannot acquire memory needed to block using a statically initialized condition variable.

#### Associated Routines

> `pthread_cond_broadcast()`
> `pthread_cond_destroy()`
> `pthread_cond_init()`
> `pthread_cond_signal()`
> `pthread_cond_wait()`
> `pthread_get_expiration_np()`

## pthread_cond_wait

> 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

C Binding #include <pthread.h>

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.

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 | Successful completion.
[EINVAL] | The value specified by cond or mutex is invalid, or Different mutexes are supplied for concurrent `pthread_cond_wait()` or `pthread_cond_timedwait()` operations on the same condition variable, or The mutex was not owned by the calling thread at the time of the call.
[ENOMEM] | The Threads Library cannot acquire memory needed to block using a statically initialized condition variable.

#### Associated Routines

> `pthread_cond_broadcast()`
> `pthread_cond_destroy()`
> `pthread_cond_init()`
> `pthread_cond_signal()`
> `pthread_cond_timedwait()`

## pthread_create

> 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 #include <pthread.h>

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.

Return Values If an error condition occurs, no thread is created, the contents of thread are undefined, and this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion.
[EAGAIN] | The system lacks the necessary resources to create another thread, or the system-imposed limit on the total number of threads under execution by a single user is exceeded.
[EINVAL] | The value specified by attr is not a valid attributes block.
[ENOMEM] | Insufficient memory exists to create a thread.
[EPERM] | The caller does not have the appropriate permission to create a thread with the specified attributes.

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

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_018.HTML