ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/users_78.htm

224 lines
7.5 KiB
HTML
Raw Permalink Normal View History

2024-04-02 14:02:31 +00:00
<!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_wait()--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_wait()--Wait for Condition</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax:
<pre> #include &lt;pthread.h&gt;
int pthread_cond_wait(pthread_cond_t *cond,
pthread_mutex_t *mutex); </pre>
&nbsp;&nbsp;Service Program Name: QP0WPTHR<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE <br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Signal Safe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>pthread_cond_wait</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_wait</strong>() is called, the calling thread must have <em>mutex</em> locked. The <strong>pthread_cond_wait</strong>() function atomically unlocks mutex and performs the wait for the condition. In this case, atomically means with respect to the mutex and the condition variable and another threads access to those objects through the pthread condition variable interfaces.</p>
<p>If the wait is satisfied, 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 issues in your application.</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 is must be locked prior to calling <strong>pthread_cond_wait</strong>().</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>cond</strong></dt>
<dd>(Input) Address of the condition variable to wait on</dd>
<dt><strong>mutex</strong></dt>
<dd>(Input) Address of the mutex associated with the condition variable</dd>
</dl>
<br>
<h3>Return Value</h3>
<dl>
<dt><strong>0</strong></dt>
<dd><strong>pthread_cond_wait</strong>() was successful.</dd>
<dt><strong>value</strong></dt>
<dd><strong>pthread_cond_wait</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_wait</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>
</dl>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>pthread.h</strong>&gt; 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 Thread<br><br></li>
<li><a href="users_77.htm">pthread_cond_timedwait()</a>--Timed 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 &lt;pthread.h&gt;
#include &lt;stdio.h&gt;
#include &quot;check.h&quot;
/* For safe condition variable usage, must use a boolean predicate and */
/* a mutex with the condition. */
int conditionMet = 0;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
#define NTHREADS 5
void *threadfunc(void *parm)
{
int rc;
rc = pthread_mutex_lock(&amp;mutex);
checkResults(&quot;pthread_mutex_lock()\n&quot;, rc);
while (!conditionMet) {
printf(&quot;Thread blocked\n&quot;);
rc = pthread_cond_wait(&amp;cond, &amp;mutex);
checkResults(&quot;pthread_cond_wait()\n&quot;, rc);
}
rc = pthread_mutex_unlock(&amp;mutex);
checkResults(&quot;pthread_mutex_lock()\n&quot;, rc);
return NULL;
}
int main(int argc, char **argv)
{
int rc=0;
int i;
pthread_t threadid[NTHREADS];
printf(&quot;Enter Testcase - %s\n&quot;, argv[0]);
printf(&quot;Create %d threads\n&quot;, NTHREADS);
for(i=0; i&lt;NTHREADS; ++i) {
rc = pthread_create(&amp;threadid[i], NULL, threadfunc, NULL);
checkResults(&quot;pthread_create()\n&quot;, rc);
}
sleep(5); /* Sleep is not a very robust way to serialize threads */
rc = pthread_mutex_lock(&amp;mutex);
checkResults(&quot;pthread_mutex_lock()\n&quot;, rc);
/* The condition has occured. Set the flag and wake up any waiting threads */
conditionMet = 1;
printf(&quot;Wake up all waiting threads...\n&quot;);
rc = pthread_cond_broadcast(&amp;cond);
checkResults(&quot;pthread_cond_broadcast()\n&quot;, rc);
rc = pthread_mutex_unlock(&amp;mutex);
checkResults(&quot;pthread_mutex_unlock()\n&quot;, rc);
printf(&quot;Wait for threads and cleanup\n&quot;);
for (i=0; i&lt;NTHREADS; ++i) {
rc = pthread_join(threadid[i], NULL);
checkResults(&quot;pthread_join()\n&quot;, rc);
}
pthread_cond_destroy(&amp;cond);
pthread_mutex_destroy(&amp;mutex);
printf(&quot;Main completed\n&quot;);
return 0;
}</pre>
<p><strong>Output:</strong></p>
<pre>Entering testcase
Create 5 threads
Thread blocked
Thread blocked
Thread blocked
Thread blocked
Thread blocked
Wake up all waiting threads...
Wait for threads and cleanup
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>