cond_timedwait(3scl)cond_timedwait(3scl)NAMEcond_timedwait - 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.
LIBRARY
SCL Threads Library (libthread.so)
SYNOPSIS
#include <synch.h>
int cond_timedwait(
cond_t *condp,
mutex_t *mutexp,
timestruc_t *abstimep );
PARAMETERS
Address of the condition variable that the calling thread waits on.
Address of the mutex associated with the condition variable specified
by condp. Absolute time at which the wait expires, if the condition
has not been signaled or broadcasted. abstimep is a pointer to a struc‐
ture of type timestruc_t, which is defined in <synch.h> as having mem‐
bers: long tv_sec; /* seconds */ long tv_nsec;
/* nanoseconds */
The tv_sec field is the number of seconds since Epoch, which is
00:00:00 CUT (Coordinated Universal Time), January 1, 1970.
DESCRIPTION
This routine causes a thread to wait until either the specified condi‐
tion variable is signaled or broadcasted, or the system time exceeds
that specified by the abstimep parameter.
This routine should be called with the specified mutex locked. The
results of this routine are unpredictable if this routine is called
without first locking the mutex.
This routine atomically unlocks 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 being unlocked. When
the timer expires or when the wait is satisfied as a result of some
other thread calling cond_signal(3scl) or cond_broadcast(3scl), the
mutex is locked again before returning to the caller.
SCL IMPLEMENTATION NOTEScond_timedwait(3scl) is implemented by calling pthread_cond_timed‐
wait(3).
cond_timedwait(3scl) first checks if the specified condition variable
and mutex are valid: if either is not, then this routine initializes
them for intra-process use (type USYNC_THREAD) by calling
pthread_cond_init(3) and/or pthread_mutex_init(3). If the mutex needed
initializing, then this routine also locks the mutex by calling
pthread_mutex_lock(3). This action matches the observed behaviour of
Solaris.
Solaris documents that cond_timedwait() always returns with the mutex
locked, even when returning an error. This is not necessarily the case
with the SCL implementation, if, for example, the specified mutex is
invalid, and the attempt to initialize the mutex, and then lock it,
fails. The best we can say is that if cond_timedwait(3scl) is called
with valid condp, mutexp and abstimep parameters, and with the mutex
locked, and cond_timedwait(3scl) returns 0 or ETIME, then the caller is
assured that the mutex is now locked. The state of the mutex for any
other status return is undefined in this implementation.
RETURN VALUES
If an error condition occurs, this routine returns an integer value
indicating the type of error.
Additional error return information may be written to the SCL error
log. Refer to scl_error_log(4scl) for details.
Possible return values are as follows:
Successful completion. Received ETIMEDOUT from pthread_cond_wait(3). A
message is written to the SCL errorlog which outlines the error-code
mapping. The timestruc_t structure pointed to by the abstimep parame‐
ter is invalid. E.g. The specified time is greater than 100,000,000
seconds in the future, or the .tv_sec field is negative. Or the
.tv_nsec field (number of nanoseconds) is greater than or equal to
1,000,000,000, or is negative. Or:
EINVAL status returned from one of: pthread_cond_init(3),
pthread_mutex_init(3), pthread_mutex_lock(3), pthread_cond_timedwait(3)
An internal implementation error occurred. Refer to the SCL errorlog
for additional information.
Note: EFAULT is not returned if any of condp, mutexp or abstimep is an
illegal address. An illegal address generates a SIGSEGV signal, which
by default will abort the process and generate a core dump.
ERRORS
None.
RELATED INFORMATION
Functions: cond_broadcast(3scl), cond_destroy(3scl), cond_init(3scl),
cond_signal(3scl), cond_wait(3scl), pthread_cond_init(3),
pthread_cond_timedwait(3), pthread_mutex_init(3),
pthread_mutex_lock(3), scl_intro(3scl), scl_thread_intro(3scl)
Files: scl_error_log(4scl)
Manuals: Solaris Compatibility Libraries User's Guide
cond_timedwait(3scl)