cond_wait()
Block a process until a condition signal is received.
Syntax
Parameters
Parameter | Definition |
|---|---|
variable | name of the variable that will end the cond_wait() condition Thevariable is issued by the cond_signal() function. |
lockname | name of the lock the cond_wait() function should attempt to acquire when it receives the correct unblocking variable in thecond_signal() function If lockname is the NULL string, thecond_wait() function will not attempt to acquire a lock after receiving variable . |
timeout | optional number of seconds to wait for the receipt of variablebefore unblocking and releasing lockname*Valid Values*
|
Specifying timeout = 0 is not permitted and will result in a PSL run-time error message.Default
infinite timeout|
Description
The cond_wait() function blocks the current PSL process until either variable is received or until timeout expires. If the PSL process holds lockname when the cond_wait() function is issued, the cond_wait() function releases the lock. When the cond_wait() function receives variable, the cond_wait() function immediately attempts to acquire lockname.
If the cond_wait() function returns a 1, it will always hold an exclusive lock on lockname. If the cond_wait() function fails, it will not hold any form of lock on lockname when it returns. If a timeout occurs, the cond_wait() function returns a failure value of "0," sets the PSL errno = 95 (E_PSL_TIMEOUT) and will not hold any lock on lockname.
condition_variable
The parameter variable is the name of the condition variable that the cond_wait() function waits to have signaled by thecond_signal() function. Condition variable names have global scope analogous to locks and shared channels. None of these different global scopes interfere with one another. You can use the same name without conflict for a lock, a shared channel, and a condition variable.
lockname
On entry to the cond_wait() function, the process releases the lock lockname and blocks waiting to be signaled. Thelockname should usually be an exclusive lock held by this process; otherwise, run-time error messages may occur (although the cond_wait() function will still try to go ahead and wait for a signal anyway). The cond_wait() function will always block waiting for the cond_signal() function or for timeout.
When another PSL process performs a cond_signal() function that wakes this PSL process, the cond_wait() function call will attempt to gain an exclusive lock (if a lock is requested, that is, if lockname is not the empty string) and either return immediately with the lock or join the queue waiting for an exclusive lock on lockname.
It is common style to supply lockname because condition variables are almost always shielded by locks. In the cond_wait()function, lockname must be supplied as the NULL string rather than omitted to force the PSL coder to consider whether a lock is needed. The required lockname reduces the number of errors caused by not using a lock when one is needed.
timeout
The behavior of timeout is unchanged regardless of whether the cond_wait() function is waiting for a cond_signal()function or waiting to acquire lockname. If variable or lockname is destroyed before the cond_wait() function is complete, the cond_wait() function returns 0 and sets the PSL errno value but will not hold any lock on lockname. The locklockname can be the NULL string, in which case variable is considered to have no associated lock; and the cond_wait()function will return success immediately upon being signaled without waiting for any lock.
Example
The following cond_wait() function waits on the signal CV1 from PASSWD_LCK before attempting to get the lock:
while ((ret = cond_wait("CV1","PASSWD_LCK",180)) != 1) {
if ((ret == 0) && (errno == 95)) {
last;
}
print("Still waiting....\n");
}
if (errno == 95) {
print("Timeout before lock was acquired\n");
} else {
print("Got the lock\n");
}