[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / condition-objects.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="semaphore-objects.html" />
<link rel="prev" href="rlock-objects.html" />
<link rel="parent" href="module-threading.html" />
<link rel="next" href="semaphore-objects.html" />
<meta name='aesop' content='information' />
<title>7.5.3 Condition Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.5.2 RLock Objects"
  href="rlock-objects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7.5 threading  "
  href="module-threading.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.5.4 Semaphore Objects"
  href="semaphore-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="rlock-objects.html">7.5.2 RLock Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-threading.html">7.5 threading  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="semaphore-objects.html">7.5.4 Semaphore Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION009530000000000000000"></A><A NAME="condition-objects"></A>
<BR>
7.5.3 Condition Objects 
</H2>

<P>
A condition variable is always associated with some kind of lock;
this can be passed in or one will be created by default.  (Passing
one in is useful when several condition variables must share the
same lock.)

<P>
A condition variable has <tt class="method">acquire()</tt> and <tt class="method">release()</tt>
methods that call the corresponding methods of the associated lock.
It also has a <tt class="method">wait()</tt> method, and <tt class="method">notify()</tt> and
<tt class="method">notifyAll()</tt> methods.  These three must only be called when
the calling thread has acquired the lock.

<P>
The <tt class="method">wait()</tt> method releases the lock, and then blocks until it
is awakened by a <tt class="method">notify()</tt> or <tt class="method">notifyAll()</tt> call for
the same condition variable in another thread.  Once awakened, it
re-acquires the lock and returns.  It is also possible to specify a
timeout.

<P>
The <tt class="method">notify()</tt> method wakes up one of the threads waiting for
the condition variable, if any are waiting.  The <tt class="method">notifyAll()</tt>
method wakes up all threads waiting for the condition variable.

<P>
Note: the <tt class="method">notify()</tt> and <tt class="method">notifyAll()</tt> methods don't
release the lock; this means that the thread or threads awakened will
not return from their <tt class="method">wait()</tt> call immediately, but only when
the thread that called <tt class="method">notify()</tt> or <tt class="method">notifyAll()</tt>
finally relinquishes ownership of the lock.

<P>
Tip: the typical programming style using condition variables uses the
lock to synchronize access to some shared state; threads that are
interested in a particular change of state call <tt class="method">wait()</tt>
repeatedly until they see the desired state, while threads that modify
the state call <tt class="method">notify()</tt> or <tt class="method">notifyAll()</tt> when they
change the state in such a way that it could possibly be a desired
state for one of the waiters.  For example, the following code is a
generic producer-consumer situation with unlimited buffer capacity:

<P>
<div class="verbatim"><pre>
# Consume one item
cv.acquire()
while not an_item_is_available():
    cv.wait()
get_an_available_item()
cv.release()

# Produce one item
cv.acquire()
make_an_item_available()
cv.notify()
cv.release()
</pre></div>

<P>
To choose between <tt class="method">notify()</tt> and <tt class="method">notifyAll()</tt>, consider
whether one state change can be interesting for only one or several
waiting threads.  E.g. in a typical producer-consumer situation,
adding one item to the buffer only needs to wake up one consumer
thread.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-2724' xml:id='l2h-2724' class="class">Condition</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>lock</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
If the <var>lock</var> argument is given and not <code>None</code>, it must be a
<tt class="class">Lock</tt> or <tt class="class">RLock</tt> object, and it is used as the underlying
lock.  Otherwise, a new <tt class="class">RLock</tt> object is created and used as
the underlying lock.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2725' xml:id='l2h-2725' class="method">acquire</tt></b>(</nobr></td>
  <td><var>*args</var>)</td></tr></table></dt>
<dd>
Acquire the underlying lock.
This method calls the corresponding method on the underlying
lock; the return value is whatever that method returns.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2726' xml:id='l2h-2726' class="method">release</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Release the underlying lock.
This method calls the corresponding method on the underlying
lock; there is no return value.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2727' xml:id='l2h-2727' class="method">wait</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>timeout</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Wait until notified or until a timeout occurs.
This must only be called when the calling thread has acquired the
lock.

<P>
This method releases the underlying lock, and then blocks until it is
awakened by a <tt class="method">notify()</tt> or <tt class="method">notifyAll()</tt> call for the
same condition variable in another thread, or until the optional
timeout occurs.  Once awakened or timed out, it re-acquires the lock
and returns.

<P>
When the <var>timeout</var> argument is present and not <code>None</code>, it
should be a floating point number specifying a timeout for the
operation in seconds (or fractions thereof).

<P>
When the underlying lock is an <tt class="class">RLock</tt>, it is not released using
its <tt class="method">release()</tt> method, since this may not actually unlock the
lock when it was acquired multiple times recursively.  Instead, an
internal interface of the <tt class="class">RLock</tt> class is used, which really
unlocks it even when it has been recursively acquired several times.
Another internal interface is then used to restore the recursion level
when the lock is reacquired.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2728' xml:id='l2h-2728' class="method">notify</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Wake up a thread waiting on this condition, if any.
This must only be called when the calling thread has acquired the
lock.

<P>
This method wakes up one of the threads waiting for the condition
variable, if any are waiting; it is a no-op if no threads are waiting.

<P>
The current implementation wakes up exactly one thread, if any are
waiting.  However, it's not safe to rely on this behavior.  A future,
optimized implementation may occasionally wake up more than one
thread.

<P>
Note: the awakened thread does not actually return from its
<tt class="method">wait()</tt> call until it can reacquire the lock.  Since
<tt class="method">notify()</tt> does not release the lock, its caller should.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2729' xml:id='l2h-2729' class="method">notifyAll</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Wake up all threads waiting on this condition.  This method acts like
<tt class="method">notify()</tt>, but wakes up all waiting threads instead of one.
</dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.5.2 RLock Objects"
  href="rlock-objects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7.5 threading  "
  href="module-threading.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.5.4 Semaphore Objects"
  href="semaphore-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="rlock-objects.html">7.5.2 RLock Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-threading.html">7.5 threading  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="semaphore-objects.html">7.5.4 Semaphore Objects</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
86530b38 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="semaphore-objects.html" />
	13	<link rel="prev" href="rlock-objects.html" />
	14	<link rel="parent" href="module-threading.html" />
	15	<link rel="next" href="semaphore-objects.html" />
	16	<meta name='aesop' content='information' />
	17	<title>7.5.3 Condition Objects </title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="7.5.2 RLock Objects"
	25	href="rlock-objects.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="7.5 threading "
	28	href="module-threading.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="7.5.4 Semaphore Objects"
	31	href="semaphore-objects.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="rlock-objects.html">7.5.2 RLock Objects</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="module-threading.html">7.5 threading </A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="semaphore-objects.html">7.5.4 Semaphore Objects</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION009530000000000000000"></A><A NAME="condition-objects"></A>
	56	<BR>
	57	7.5.3 Condition Objects
	58	</H2>
	59
	60	<P>
	61	A condition variable is always associated with some kind of lock;
	62	this can be passed in or one will be created by default. (Passing
	63	one in is useful when several condition variables must share the
	64	same lock.)
65
66	<P>
67	A condition variable has <tt class="method">acquire()</tt> and <tt class="method">release()</tt>
68	methods that call the corresponding methods of the associated lock.
69	It also has a <tt class="method">wait()</tt> method, and <tt class="method">notify()</tt> and
70	<tt class="method">notifyAll()</tt> methods. These three must only be called when
71	the calling thread has acquired the lock.
72
73	<P>
74	The <tt class="method">wait()</tt> method releases the lock, and then blocks until it
75	is awakened by a <tt class="method">notify()</tt> or <tt class="method">notifyAll()</tt> call for
76	the same condition variable in another thread. Once awakened, it
77	re-acquires the lock and returns. It is also possible to specify a
78	timeout.
79
80	<P>
81	The <tt class="method">notify()</tt> method wakes up one of the threads waiting for
82	the condition variable, if any are waiting. The <tt class="method">notifyAll()</tt>
83	method wakes up all threads waiting for the condition variable.
84
85	<P>
86	Note: the <tt class="method">notify()</tt> and <tt class="method">notifyAll()</tt> methods don't
87	release the lock; this means that the thread or threads awakened will
88	not return from their <tt class="method">wait()</tt> call immediately, but only when
89	the thread that called <tt class="method">notify()</tt> or <tt class="method">notifyAll()</tt>
90	finally relinquishes ownership of the lock.
91
92	<P>
93	Tip: the typical programming style using condition variables uses the
94	lock to synchronize access to some shared state; threads that are
95	interested in a particular change of state call <tt class="method">wait()</tt>
96	repeatedly until they see the desired state, while threads that modify
97	the state call <tt class="method">notify()</tt> or <tt class="method">notifyAll()</tt> when they
98	change the state in such a way that it could possibly be a desired
99	state for one of the waiters. For example, the following code is a
100	generic producer-consumer situation with unlimited buffer capacity:
101
102	<P>
103	<div class="verbatim"><pre>
104	# Consume one item
105	cv.acquire()
106	while not an_item_is_available():
107	cv.wait()
108	get_an_available_item()
109	cv.release()
110
111	# Produce one item
112	cv.acquire()
113	make_an_item_available()
114	cv.notify()
115	cv.release()
116	</pre></div>
117
118	<P>
119	To choose between <tt class="method">notify()</tt> and <tt class="method">notifyAll()</tt>, consider
120	whether one state change can be interesting for only one or several
121	waiting threads. E.g. in a typical producer-consumer situation,
122	adding one item to the buffer only needs to wake up one consumer
123	thread.
124
125	<P>
126	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
127	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-2724' xml:id='l2h-2724' class="class">Condition</tt></b>(</nobr></td>
128	<td><var></var><big>[</big><var>lock</var><big>]</big><var></var>)</td></tr></table></dt>
129	<dd>
130	If the <var>lock</var> argument is given and not <code>None</code>, it must be a
131	<tt class="class">Lock</tt> or <tt class="class">RLock</tt> object, and it is used as the underlying
132	lock. Otherwise, a new <tt class="class">RLock</tt> object is created and used as
133	the underlying lock.
134	</dl>
135
136	<P>
137	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
138	<td><nobr><b><tt id='l2h-2725' xml:id='l2h-2725' class="method">acquire</tt></b>(</nobr></td>
139	<td><var>*args</var>)</td></tr></table></dt>
140	<dd>
141	Acquire the underlying lock.
142	This method calls the corresponding method on the underlying
143	lock; the return value is whatever that method returns.
144	</dl>
145
146	<P>
147	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
148	<td><nobr><b><tt id='l2h-2726' xml:id='l2h-2726' class="method">release</tt></b>(</nobr></td>
149	<td><var></var>)</td></tr></table></dt>
150	<dd>
151	Release the underlying lock.
152	This method calls the corresponding method on the underlying
153	lock; there is no return value.
154	</dl>
155
156	<P>
157	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
158	<td><nobr><b><tt id='l2h-2727' xml:id='l2h-2727' class="method">wait</tt></b>(</nobr></td>
159	<td><var></var><big>[</big><var>timeout</var><big>]</big><var></var>)</td></tr></table></dt>
160	<dd>
161	Wait until notified or until a timeout occurs.
162	This must only be called when the calling thread has acquired the
163	lock.
164
165	<P>
166	This method releases the underlying lock, and then blocks until it is
167	awakened by a <tt class="method">notify()</tt> or <tt class="method">notifyAll()</tt> call for the
168	same condition variable in another thread, or until the optional
169	timeout occurs. Once awakened or timed out, it re-acquires the lock
170	and returns.
171
172	<P>
173	When the <var>timeout</var> argument is present and not <code>None</code>, it
174	should be a floating point number specifying a timeout for the
175	operation in seconds (or fractions thereof).
176
177	<P>
178	When the underlying lock is an <tt class="class">RLock</tt>, it is not released using
179	its <tt class="method">release()</tt> method, since this may not actually unlock the
180	lock when it was acquired multiple times recursively. Instead, an
181	internal interface of the <tt class="class">RLock</tt> class is used, which really
182	unlocks it even when it has been recursively acquired several times.
183	Another internal interface is then used to restore the recursion level
184	when the lock is reacquired.
185	</dl>
186
187	<P>
188	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
189	<td><nobr><b><tt id='l2h-2728' xml:id='l2h-2728' class="method">notify</tt></b>(</nobr></td>
190	<td><var></var>)</td></tr></table></dt>
191	<dd>
192	Wake up a thread waiting on this condition, if any.
193	This must only be called when the calling thread has acquired the
194	lock.
195
196	<P>
197	This method wakes up one of the threads waiting for the condition
198	variable, if any are waiting; it is a no-op if no threads are waiting.
199
200	<P>
201	The current implementation wakes up exactly one thread, if any are
202	waiting. However, it's not safe to rely on this behavior. A future,
203	optimized implementation may occasionally wake up more than one
204	thread.
205
206	<P>
207	Note: the awakened thread does not actually return from its
208	<tt class="method">wait()</tt> call until it can reacquire the lock. Since
209	<tt class="method">notify()</tt> does not release the lock, its caller should.
210	</dl>
211
212	<P>
213	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
214	<td><nobr><b><tt id='l2h-2729' xml:id='l2h-2729' class="method">notifyAll</tt></b>(</nobr></td>
215	<td><var></var>)</td></tr></table></dt>
216	<dd>
217	Wake up all threads waiting on this condition. This method acts like
218	<tt class="method">notify()</tt>, but wakes up all waiting threads instead of one.
219	</dl>
220
221	<P>
222
223	<DIV CLASS="navigation">
224	<div class='online-navigation'>
225	<p></p><hr />
226	<table align="center" width="100%" cellpadding="0" cellspacing="2">
227	<tr>
228	<td class='online-navigation'><a rel="prev" title="7.5.2 RLock Objects"
229	href="rlock-objects.html"><img src='../icons/previous.png'
230	border='0' height='32' alt='Previous Page' width='32' /></A></td>
231	<td class='online-navigation'><a rel="parent" title="7.5 threading "
232	href="module-threading.html"><img src='../icons/up.png'
233	border='0' height='32' alt='Up One Level' width='32' /></A></td>
234	<td class='online-navigation'><a rel="next" title="7.5.4 Semaphore Objects"
235	href="semaphore-objects.html"><img src='../icons/next.png'
236	border='0' height='32' alt='Next Page' width='32' /></A></td>
237	<td align="center" width="100%">Python Library Reference</td>
238	<td class='online-navigation'><a rel="contents" title="Table of Contents"
239	href="contents.html"><img src='../icons/contents.png'
240	border='0' height='32' alt='Contents' width='32' /></A></td>
241	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
242	border='0' height='32' alt='Module Index' width='32' /></a></td>
243	<td class='online-navigation'><a rel="index" title="Index"
244	href="genindex.html"><img src='../icons/index.png'
245	border='0' height='32' alt='Index' width='32' /></A></td>
246	</tr></table>
247	<div class='online-navigation'>
248	<b class="navlabel">Previous:</b>
249	<a class="sectref" rel="prev" href="rlock-objects.html">7.5.2 RLock Objects</A>
250	<b class="navlabel">Up:</b>
251	<a class="sectref" rel="parent" href="module-threading.html">7.5 threading </A>
252	<b class="navlabel">Next:</b>
253	<a class="sectref" rel="next" href="semaphore-objects.html">7.5.4 Semaphore Objects</A>
254	</div>
255	</div>
256	<hr />
257	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
258	</DIV>
259	<!--End of Navigation Panel-->
260	<ADDRESS>
261	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
262	</ADDRESS>
263	</BODY>
264	</HTML>