Guide to DECthreads

int
pthread_cond_signal (
pthread_cond_t *cond);

ARGUMENTS

cond

Condition variable to be signaled.

DESCRIPTION

This routine unblocks at least one thread waiting on the specified condition variable cond. Calling this routine implies that data guarded by the associated mutex has changed, so that it might be possible for one of the waiting threads to proceed. In general, only one will be released.

If no threads are waiting on the specified condition variable, then this routine takes no action. The signal does not propagate to the next condition variable wait.

This routine should be called when any thread waiting on the specified condition variable might find its predicate true, but only one thread should proceed. If more than one thread can proceed, or if any thread would not be able to proceed, then you must use pthread_cond_broadcast().

The scheduling policy determines 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 even when the associated mutex is locked. However, if predictable scheduling behavior is required, then that mutex should be locked by the thread calling pthread_cond_signal().

Associated Routines

• pthread_cond_broadcast()
• pthread_cond_destroy()
• pthread_cond_init()
• pthread_cond_timedwait()
• pthread_cond_wait()

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

Syntax

pthread_cond_signal_int_np(
cond );

Argument	Data Type	Access
cond	opaque pthread_cond_t	modify

int
pthread_cond_signal_int_np(
pthread_cond_t *cond);

ARGUMENTS

cond

Condition variable to be signaled.

DESCRIPTION

This routine wakes one thread waiting on a condition variable. It can only be called from a software interrupt handler routine (such as from a Digital UNIX signal handler or OpenVMS AST). Calling this routine implies that it might be possible for a single waiting thread to proceed.

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.

This routine does not cause a thread blocked on a condition variable to resume execution immediately. A thread resumes execution at some time after the interrupt handler returns.

You can call this routine regardless of whether the associated mutex is locked.

Never try to lock a mutex from an interrupt handler.

---

Note

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

---

Associated Routines

• pthread_cond_wait()
• pthread_cond_timedwait()
• pthread_cond_signal()
• pthread_cond_broadcast()

Causes a thread to wait for a 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

int
pthread_cond_timedwait (
pthread_cond_t *cond,
pthread_mutex_t *mutex,
const struct timespec *abstime);

ARGUMENTS

cond

Condition variable that a 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 a 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, without releasing the mutex or causing the current thread to wait. 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.

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

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

ARGUMENTS

cond

Condition variable that a thread waits on.

mutex

Mutex associated with the condition variable specified in cond.

DESCRIPTION

This routine causes a thread to wait for a 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 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.

Associated Routines

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

Destroys a condition variable attributes object.

Syntax

pthread_condattr_destroy(
attr );

Argument	Data Type	Access
attr	opaque pthread_condattr_t	write

int
pthread_condattr_destroy (
pthread_condattr_t *attr);

ARGUMENTS

attr

Condition variable attributes object to be destroyed.

DESCRIPTION

This routine destroys a condition variable attributes object---that is, the object becomes uninitialized.

Condition variables that were created using this attributes object are not affected by the deletion of the condition variable attributes object.

After calling this routine, the results of using attr in a call to any routine (other than pthread_condattr_init()) are unpredictable.

Currently, no attributes affecting condition variables are defined. You cannot change any attributes in the condition variable attributes object.

The pthread_condattr_init() and pthread_condattr_destroy() routines are provided for future expandability of the DECthreads pthread interface and to conform with the POSIX.1c standard. These routines serve no useful function, because there are no pthread_condattr_set*() type routines available at this time.

Associated Routines

• pthread_condattr_init()

Initializes a condition variable attributes object that can be used to specify the attributes of condition variables when they are created.

Syntax

pthread_condattr_init(
attr );

Argument	Data Type	Access
attr	opaque pthread_condattr_t	write

int
pthread_condattr_init (
pthread_condattr_t *attr);

ARGUMENTS

attr

Condition variable attributes object to initialize.

DESCRIPTION

This routine initializes the condition variable attributes object (attr) that is used to specify the attributes of condition variables when they are initialized. The condition variable attributes object is initialized with the default attribute values.

When a condition variable attributes object is used to initialize a condition variable, the values of the individual attributes determine the characteristics of the new object. Attributes objects act like additional arguments to object initialization. Changing individual attributes does not affect objects that were previously initialized using the attributes object.

Currently, no attributes affecting condition variables are defined. You cannot change any attributes in the condition variable attributes object.

The pthread_condattr_init() and pthread_condattr_destroy() routines are provided for future expandability of the DECthreads pthread interface and to conform with the POSIX.1c standard. These routines serve no useful function, because there are no pthread_condattr_set*() type routines available at this time.

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.
[ENOMEM]	Insufficient memory exists to initialize the condition variable attributes object.

Associated Routines

• pthread_condattr_destroy()
• pthread_cond_init()

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

Thread object 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).
• 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

A thread is created in the ready state to begin executing the function specified by the start_routine argument. The new thread may execute immediately. The newly created thread may preempt its creator, depending on scheduling policy and priority. The thread identifier specified in pthread_create() will be written before the new thread executes.

The new thread's scheduling policy and priority are, by default, inherited from the creating thread---that is, the scheduling policy and priority set in the attributes object are ignored. To create a thread using the scheduling policy and priority set in the attributes object, you must first disable the inherit scheduling attribute by calling pthread_attr_setinheritsched() before calling pthread_create().

The 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 caller of pthread_create() can synchronize with the newly created thread through the use of the pthread_join() routine, or any other mutexes or condition variables they agree to use.

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.
• An exception is raised (or re-raised) in the thread during execution, and the exception is not handled.
• 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:
   • 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 on the terminated thread (using pthread_join()). See Section 2.3.5 for a description of joining on a thread.

   ---

   Note

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

   ---

2. If the termination results from a cancelation, a call to pthread_exit(), or an unhandled exception, 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 FINALY 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 must call the appropriate destructor functions, just as if an exception has 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.5 for more information about thread-specific data.
5. DECthreads awakens the thread (if there is one) that is currently joined on 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 on. 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()

Invokes the DECthreads internal debugger.

Syntax

pthread_debug( );

void
pthread_debug (void);

ARGUMENTS

None

DESCRIPTION

This routine invokes the DECthreads internal debugger as a callable function. It takes no arguments and does not return a value. It enters the internal debugger parsing loop. Type exit to return to the program.

To pass a list of debugging commands to DECthreads, call pthread_debug_cmd().

For more information, see Appendix D.

Associated Routines

• pthread_debug_cmd()

Passes a list of pthread_debug() commands to DECthreads.

Syntax

pthread_debug_cmd(
cmd );

Argument	Data Type	Access
cmd	character string	read

  6493P009.HTM
  OSSG Documentation
  22-NOV-1996 13:20:09.42

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal