232 lines
7.5 KiB
HTML
232 lines
7.5 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_signal()--Signal Condition to One Waiting Thread</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 -->
|
||
|
|
<!--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_signal()--Signal Condition to One Waiting Thread</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax:
|
||
|
|
<pre> #include <pthread.h>
|
||
|
|
int pthread_cond_signal(pthread_cond_t *cond); </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_signal</strong>() function wakes up at least one thread that is currently waiting on the condition variable specified by <em>cond</em>. If no threads are currently blocked on the condition variable, this call has no effect.</p>
|
||
|
|
|
||
|
|
<p>When the thread that was the target of the signal wakes up, it contends for the mutex that it has associated with the condition variable on the call to <strong>pthread_cond_timedwait</strong>() or <strong>pthread_cond_wait</strong>().</p>
|
||
|
|
|
||
|
|
<p>The signal and broadcast functions can be called by a thread whether or not it currently owns the mutex associated with the condition variable. If predictable scheduling behavior is required from the applications viewpoint, however, the mutex should be locked by the thread that calls <strong>pthread_cond_signal</strong>() or <strong>pthread_cond_broadcast</strong>().</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>None.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>cond</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Address of the condition variable to be signaled</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>0</strong></dt>
|
||
|
|
|
||
|
|
<dd><strong>pthread_cond_signal</strong>() was successful.</dd>
|
||
|
|
|
||
|
|
<dt><strong>value</strong></dt>
|
||
|
|
|
||
|
|
<dd><strong>pthread_cond_signal</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_signal</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 condition specified is not valid.</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_77.htm">pthread_cond_timedwait()</a>--Timed Wait for Condition<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 <pthread.h>
|
||
|
|
#include <stdio.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 2
|
||
|
|
|
||
|
|
void *threadfunc(void *parm)
|
||
|
|
{
|
||
|
|
int rc;
|
||
|
|
|
||
|
|
while (1) {
|
||
|
|
/* Usually worker threads will loop on these operations */
|
||
|
|
rc = pthread_mutex_lock(&mutex);
|
||
|
|
checkResults("pthread_mutex_lock()\n", rc);
|
||
|
|
|
||
|
|
while (!workToDo) {
|
||
|
|
printf("Thread blocked\n");
|
||
|
|
rc = pthread_cond_wait(&cond, &mutex);
|
||
|
|
checkResults("pthread_cond_wait()\n", rc);
|
||
|
|
}
|
||
|
|
printf("Thread awake, finish work!\n");
|
||
|
|
|
||
|
|
/* Under protection of the lock, complete or remove the work */
|
||
|
|
/* from whatever worker queue we have. Here it is simply a flag */
|
||
|
|
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);
|
||
|
|
}
|
||
|
|
|
||
|
|
sleep(5); /* Sleep is not a very robust way to serialize threads */
|
||
|
|
|
||
|
|
for(i=0; i<5; ++i) {
|
||
|
|
printf("Wake up a worker, work to do...\n");
|
||
|
|
|
||
|
|
rc = pthread_mutex_lock(&mutex);
|
||
|
|
checkResults("pthread_mutex_lock()\n", rc);
|
||
|
|
|
||
|
|
/* In the real world, all the threads might be busy, and */
|
||
|
|
/* we would add work to a queue instead of simply using a flag */
|
||
|
|
/* In that case the boolean predicate might be some boolean */
|
||
|
|
/* statement like: if (the-queue-contains-work) */
|
||
|
|
if (workToDo) {
|
||
|
|
printf("Work already present, likely threads are busy\n");
|
||
|
|
}
|
||
|
|
workToDo = 1;
|
||
|
|
rc = pthread_cond_signal(&cond);
|
||
|
|
checkResults("pthread_cond_broadcast()\n", rc);
|
||
|
|
|
||
|
|
rc = pthread_mutex_unlock(&mutex);
|
||
|
|
checkResults("pthread_mutex_unlock()\n", rc);
|
||
|
|
sleep(5); /* Sleep is not a very robust way to serialize threads */
|
||
|
|
}
|
||
|
|
|
||
|
|
printf("Main completed\n");
|
||
|
|
exit(0);
|
||
|
|
return 0;
|
||
|
|
}</pre>
|
||
|
|
|
||
|
|
<p><strong>Output:</strong></p>
|
||
|
|
|
||
|
|
<pre>Enter Testcase - QP0WTEST/TPCOS0
|
||
|
|
Create 2 threads
|
||
|
|
Thread blocked
|
||
|
|
Thread blocked
|
||
|
|
Wake up a worker, work to do...
|
||
|
|
Thread awake, finish work!
|
||
|
|
Thread blocked
|
||
|
|
Wake up a worker, work to do...
|
||
|
|
Thread awake, finish work!
|
||
|
|
Thread blocked
|
||
|
|
Wake up a worker, work to do...
|
||
|
|
Thread awake, finish work!
|
||
|
|
Thread blocked
|
||
|
|
Wake up a worker, work to do...
|
||
|
|
Thread awake, finish work!
|
||
|
|
Thread blocked
|
||
|
|
Wake up a worker, work to do...
|
||
|
|
Thread awake, finish work!
|
||
|
|
Thread blocked
|
||
|
|
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>
|