270 lines
10 KiB
HTML
270 lines
10 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>pthread_cond_timedwait()--Timed Wait for Condition</title>
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Begin Header Records ========================================== -->
|
|
<!-- NETMG2 SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
|
<!-- RCHVMW2 on 29 Jan 1999 at 10:01:37 -->
|
|
<!-- Change History: -->
|
|
<!-- 030924 XZY1406 EPERM, not ENOTLOCKED, P9A40991, V5R3 -->
|
|
<!--File Edited November 2001 -->
|
|
<!--End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
|
|
<!-- Java sync-link -->
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
|
|
<a name="Top_Of_Page"></a>
|
|
|
|
<h2>pthread_cond_timedwait()--Timed Wait for Condition</h2>
|
|
|
|
<div class="box" style="width: 60%;">
|
|
<br>
|
|
Syntax:
|
|
<pre> #include <pthread.h>
|
|
#include <time.h>
|
|
int pthread_cond_timedwait(pthread_cond_t *cond,
|
|
pthread_mutex_t *mutex,
|
|
const struct timespec *abstime); </pre>
|
|
Service Program Name: QP0WPTHR<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE <br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Signal Safe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The <strong>pthread_cond_timedwait</strong>() function blocks the calling thread, waiting for the condition specified by <em>cond</em> to be signaled or broadcast to.</p>
|
|
|
|
<p>When <strong>pthread_cond_timedwait</strong>() is called, the calling thread must have <em>mutex</em> locked. The <strong>pthread_cond_timedwait</strong>() function atomically unlocks the mutex and performs the wait for the condition. In this case, atomically means with respect to the mutex and the condition variable and other access by threads to those objects through the pthread condition variable interfaces.</p>
|
|
|
|
<p>If the wait is satisfied or times out, or if the thread is canceled, before the thread is allowed to continue, the mutex is automatically acquired by the calling thread. If <em>mutex</em> is not currently locked, an <strong>EPERM</strong> error results. You should always associate only one mutex with a condition at a time. Using two different mutexes with the same condition at the same time could lead to unpredictable serialization in your application.</p>
|
|
|
|
<p>The time to wait is specified by the <em>abstime</em> parameter as an absolute system time at which the wait expires. If the current system clock time passes the absolute time specified before the condition is signaled, an <strong>ETIMEDOUT</strong> error results. After the wait begins, the wait time is not affected by changes to the system clock.</p>
|
|
|
|
<p>Although time is specified in seconds and nanoseconds, the system has approximately millisecond granularity. Due to scheduling and priorities, the amount of time you actually wait might be slightly more or less than the amount of time specified.</p>
|
|
|
|
<p>The current absolute system time can be retrieved as a timeval structure using the system clock interface <strong>gettimeofday</strong>(). The timeval structure can easily have a delta value added to it and be converted to a timespec structure. The MI time interfaces can be used to retrieve the current system time. The MI time also needs to be converted to a timespec structure before use by <strong>pthread_cond_timedwait</strong>() using the <strong>Qp0zConvertTime</strong>() interface.</p>
|
|
|
|
<p>This function is a cancellation point.</p>
|
|
|
|
<p><strong>Note:</strong> For dependable use of condition variables, and to ensure that you do not lose wake-up operations on condition variables, your application should always use a Boolean predicate and a mutex with the condition variable.</p>
|
|
|
|
<br>
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<p>For successful completion, the mutex lock associated with the condition variable must be locked before you call <strong>pthread_cond_timedwait</strong>().</p>
|
|
|
|
<br>
|
|
<h3>Parameters</h3>
|
|
|
|
<dl>
|
|
<dt><strong>cond</strong></dt>
|
|
|
|
<dd>(Input) Address of the condition variable to wait for</dd>
|
|
|
|
<dt><strong>mutex</strong></dt>
|
|
|
|
<dd>(Input) Address of the locked mutex associated with the condition variable</dd>
|
|
|
|
<dt><strong>abstime</strong></dt>
|
|
|
|
<dd>(Input) Address of the absolute system time at which the wait expires</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Return Value</h3>
|
|
|
|
<dl>
|
|
<dt><strong>0</strong></dt>
|
|
|
|
<dd><strong>pthread_cond_timedwait</strong>() was successful.</dd>
|
|
|
|
<dt><strong>value</strong></dt>
|
|
|
|
<dd><strong>pthread_cond_timedwait</strong>() was not successful. <em>value</em> is set to indicate the error condition.</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Error Conditions</h3>
|
|
|
|
<p>If <strong>pthread_cond_timedwait</strong>() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.</p>
|
|
|
|
<dl>
|
|
<dt><em>[EINVAL]</em></dt>
|
|
|
|
<dd><p>The value specified for the argument is not correct.</p></dd>
|
|
|
|
<dt><em>[EPERM]</em></dt>
|
|
|
|
<dd><p>The mutex specified is not locked by the caller.</p></dd>
|
|
|
|
<dt><em>[ETIMEDOUT]</em></dt>
|
|
|
|
<dd><p>The wait timed out without being satisfied.</p></dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li>The <<strong>pthread.h</strong>> header file. See <a href="rzah4hed.htm">Header files for Pthread functions</a>.<br><br></li>
|
|
|
|
<li><a href="users_73.htm">pthread_cond_broadcast()</a>--Broadcast Condition to All Waiting Threads<br><br></li>
|
|
|
|
<li><a href="users_75.htm">pthread_cond_init()</a>--Initialize Condition Variable<br><br></li>
|
|
|
|
<li><a href="users_76.htm">pthread_cond_signal()</a>--Signal Condition to One Waiting Threads<br><br></li>
|
|
|
|
<li><a href="users_78.htm">pthread_cond_wait()</a>--Wait for Condition</li>
|
|
</ul>
|
|
|
|
<br>
|
|
<h3>Example</h3>
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
|
for information pertaining to code examples.</p>
|
|
<pre>#define _MULTI_THREADED
|
|
#include <stdio.h>
|
|
#include <qp0z1170.h>
|
|
#include <time.h>
|
|
#include <pthread.h>
|
|
#include "check.h"
|
|
|
|
/* For safe condition variable usage, must use a boolean predicate and */
|
|
/* a mutex with the condition. */
|
|
int workToDo = 0;
|
|
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
|
|
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
|
|
|
|
#define NTHREADS 3
|
|
#define WAIT_TIME_SECONDS 15
|
|
|
|
void *threadfunc(void *parm)
|
|
{
|
|
int rc;
|
|
struct timespec ts;
|
|
struct timeval tp;
|
|
|
|
rc = pthread_mutex_lock(&mutex);
|
|
checkResults("pthread_mutex_lock()\n", rc);
|
|
|
|
/* Usually worker threads will loop on these operations */
|
|
while (1) {
|
|
rc = gettimeofday(&tp, NULL);
|
|
checkResults("gettimeofday()\n", rc);
|
|
|
|
/* Convert from timeval to timespec */
|
|
ts.tv_sec = tp.tv_sec;
|
|
ts.tv_nsec = tp.tv_usec * 1000;
|
|
ts.tv_sec += WAIT_TIME_SECONDS;
|
|
|
|
while (!workToDo) {
|
|
printf("Thread blocked\n");
|
|
rc = pthread_cond_timedwait(&cond, &mutex, &ts);
|
|
/* If the wait timed out, in this example, the work is complete, and */
|
|
/* the thread will end. */
|
|
/* In reality, a timeout must be accompanied by some sort of checking */
|
|
/* to see if the work is REALLY all complete. In the simple example */
|
|
/* we will just go belly up when we time out. */
|
|
if (rc == ETIMEDOUT) {
|
|
printf("Wait timed out!\n");
|
|
rc = pthread_mutex_unlock(&mutex);
|
|
checkResults("pthread_mutex_lock()\n", rc);
|
|
pthread_exit(NULL);
|
|
}
|
|
checkResults("pthread_cond_timedwait()\n", rc);
|
|
}
|
|
|
|
printf("Thread consumes work here\n");
|
|
workToDo = 0;
|
|
}
|
|
|
|
rc = pthread_mutex_unlock(&mutex);
|
|
checkResults("pthread_mutex_lock()\n", rc);
|
|
return NULL;
|
|
}
|
|
|
|
int main(int argc, char **argv)
|
|
{
|
|
int rc=0;
|
|
int i;
|
|
pthread_t threadid[NTHREADS];
|
|
|
|
printf("Enter Testcase - %s\n", argv[0]);
|
|
|
|
printf("Create %d threads\n", NTHREADS);
|
|
for(i=0; i<NTHREADS; ++i) {
|
|
rc = pthread_create(&threadid[i], NULL, threadfunc, NULL);
|
|
checkResults("pthread_create()\n", rc);
|
|
}
|
|
|
|
rc = pthread_mutex_lock(&mutex);
|
|
checkResults("pthread_mutex_lock()\n", rc);
|
|
|
|
printf("One work item to give to a thread\n");
|
|
workToDo = 1;
|
|
rc = pthread_cond_signal(&cond);
|
|
checkResults("pthread_cond_signal()\n", rc);
|
|
|
|
rc = pthread_mutex_unlock(&mutex);
|
|
checkResults("pthread_mutex_unlock()\n", rc);
|
|
|
|
printf("Wait for threads and cleanup\n");
|
|
for (i=0; i<NTHREADS; ++i) {
|
|
rc = pthread_join(threadid[i], NULL);
|
|
checkResults("pthread_join()\n", rc);
|
|
}
|
|
|
|
pthread_cond_destroy(&cond);
|
|
pthread_mutex_destroy(&mutex);
|
|
printf("Main completed\n");
|
|
return 0;
|
|
}</pre>
|
|
|
|
<p><strong>Output:</strong></p>
|
|
|
|
<pre>Enter Testcase - QP0WTEST/TPCOT0
|
|
Create 3 threads
|
|
Thread blocked
|
|
One work item to give to a thread
|
|
Wait for threads and cleanup
|
|
Thread consumes work here
|
|
Thread blocked
|
|
Thread blocked
|
|
Thread blocked
|
|
Wait timed out!
|
|
Wait timed out!
|
|
Wait timed out!
|
|
Main completed</pre>
|
|
|
|
<hr>
|
|
API introduced: V4R3
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> |
|
|
<a href="rzah4mst.htm">Pthread APIs</a> |
|
|
<a href="aplist.htm">APIs by category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
</body>
|
|
</html>
|