sam-t2/devtools/amd64/html/python/lib/semaphore-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="event-objects.html" />
<link rel="prev" href="condition-objects.html" />
<link rel="parent" href="module-threading.html" />
<link rel="next" href="semaphore-examples.html" />
<meta name='aesop' content='information' />
<title>7.5.4 Semaphore 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.3 Condition Objects"
  href="condition-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.1 Semaphore Example"
  href="semaphore-examples.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="condition-objects.html">7.5.3 Condition 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-examples.html">7.5.4.1 Semaphore Example</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION009540000000000000000"></A><A NAME="semaphore-objects"></A>
<BR>
7.5.4 Semaphore Objects
</H2>

<P>
This is one of the oldest synchronization primitives in the history of
computer science, invented by the early Dutch computer scientist
Edsger W. Dijkstra (he used <tt class="method">P()</tt> and <tt class="method">V()</tt> instead of
<tt class="method">acquire()</tt> and <tt class="method">release()</tt>).

<P>
A semaphore manages an internal counter which is decremented by each
<tt class="method">acquire()</tt> call and incremented by each <tt class="method">release()</tt>
call.  The counter can never go below zero; when <tt class="method">acquire()</tt>
finds that it is zero, it blocks, waiting until some other thread
calls <tt class="method">release()</tt>.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-2730' xml:id='l2h-2730' class="class">Semaphore</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>value</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
The optional argument gives the initial value for the internal
counter; it defaults to <code>1</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2731' xml:id='l2h-2731' class="method">acquire</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>blocking</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Acquire a semaphore.

<P>
When invoked without arguments: if the internal counter is larger than
zero on entry, decrement it by one and return immediately.  If it is
zero on entry, block, waiting until some other thread has called
<tt class="method">release()</tt> to make it larger than zero.  This is done with
proper interlocking so that if multiple <tt class="method">acquire()</tt> calls are
blocked, <tt class="method">release()</tt> will wake exactly one of them up.  The
implementation may pick one at random, so the order in which blocked
threads are awakened should not be relied on.  There is no return
value in this case.

<P>
When invoked with <var>blocking</var> set to true, do the same thing as
when called without arguments, and return true.

<P>
When invoked with <var>blocking</var> set to false, do not block.  If a
call without an argument would block, return false immediately;
otherwise, do the same thing as when called without arguments, and
return true.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2732' xml:id='l2h-2732' class="method">release</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Release a semaphore,
incrementing the internal counter by one.  When it was zero on
entry and another thread is waiting for it to become larger
than zero again, wake up that thread.
</dl>

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="semaphore-examples.html">7.5.4.1 <tt class="class">Semaphore</tt> Example</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<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.3 Condition Objects"
  href="condition-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.1 Semaphore Example"
  href="semaphore-examples.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="condition-objects.html">7.5.3 Condition 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-examples.html">7.5.4.1 Semaphore Example</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>