[Python-checkins] CVS: python/dist/src/Doc/lib libthreading.tex,1.9,1.9.4.1

[Guido van Rossum]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv30284/lib

Modified Files:
      Tag: r22a2-branch
	libthreading.tex 
Log Message:
Merge the Docs from the trunk for the last time.

Index: libthreading.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libthreading.tex,v
retrieving revision 1.9
retrieving revision 1.9.4.1
diff -C2 -d -r1.9 -r1.9.4.1
*** libthreading.tex	2001/07/06 20:30:11	1.9
--- libthreading.tex	2001/08/21 03:05:17	1.9.4.1
***************
*** 61,72 ****
  \end{funcdesc}
  
! \begin{funcdesc}{Semaphore}{}
  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.
  \end{funcdesc}
  
  \begin{classdesc*}{Thread}{}
  A class that represents a thread of control.  This class can be safely subclassed in a limited fashion.
--- 61,82 ----
  \end{funcdesc}
  
! \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.  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}{}
  A class that represents a thread of control.  This class can be safely subclassed in a limited fashion.
***************
*** 367,370 ****
--- 377,408 ----
  \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}}