Added documentation for BoundedSemaphore(), contributed by Skip Montanaro.

This closes SF patch #452836.

1 files changed, 40 insertions, 2 deletions

diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex
index e896a84..27503bd 100644
--- a/Doc/lib/libthreading.tex
+++ b/Doc/lib/libthreading.tex
@@ -60,12 +60,22 @@ acquire it again without blocking; the thread must release it once
 for each time it has acquired it.
 \end{funcdesc}
 
-\begin{funcdesc}{Semaphore}{}
+\begin{funcdesc}{Semaphore}{\optional{value}}
 A factory function that returns a new semaphore object.  A
 semaphore manages a counter representing the number of \method{release()}
 calls minus the number of \method{acquire()} calls, plus an initial value.
 The \method{acquire()} method blocks if necessary until it can return
-without making the counter negative.
+without making the counter negative.  If not given, \var{value} defaults to
+1. 
+\end{funcdesc}
+
+\begin{funcdesc}{BoundedSemaphore}{\optional{value}}
+A factory function that returns a new bounded semaphore object.  A bounded
+semaphore checks to make sure its current value doesn't exceed its initial
+value.  If it does, \exception{ValueError} is raised. In most situations
+semaphores are used to guard resources with limited capacity.  If the
+semaphore is released too many times it's a sign of a bug.  If not given,
+\var{value} defaults to 1. 
 \end{funcdesc}
 
 \begin{classdesc*}{Thread}{}
@@ -367,6 +377,34 @@ than zero again, wake up that thread.
 \end{methoddesc}
 
 
+\subsubsection{\class{Semaphore} Example \label{semaphore-examples}}
+
+Semaphores are often used to guard resources with limited capacity, for
+example, a database server.  In any situation where the size of the resource
+size is fixed, you should use a bounded semaphore.  Before spawning any
+worker threads, your main thread would initialize the semaphore:
+
+\begin{verbatim}
+maxconnections = 5
+...
+pool_sema = BoundedSemaphore(value=maxconnections)
+\end{verbatim}
+
+Once spawned, worker threads call the semaphore's acquire and release
+methods when they need to connect to the server:
+
+\begin{verbatim}
+pool_sema.acquire()
+conn = connectdb()
+... use connection ...
+conn.close()
+pool_sema.release()
+\end{verbatim}
+
+The use of a bounded semaphore reduces the chance that a programming error
+which causes the semaphore to be released more than it's acquired will go
+undetected.
+
 \subsection{Event Objects \label{event-objects}}
 
 This is one of the simplest mechanisms for communication between