From bf5a6d2eb4664f6508a74e7890abe6b07504e6b0 Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Fri, 12 Mar 1999 19:57:38 +0000 Subject: Fixed tons of small markup problems. --- Doc/lib/libthreading.tex | 143 ++++++++++++++++++++++++----------------------- 1 file changed, 74 insertions(+), 69 deletions(-) diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex index d2c5ff3..343cc74 100644 --- a/Doc/lib/libthreading.tex +++ b/Doc/lib/libthreading.tex @@ -1,8 +1,8 @@ \section{\module{threading} --- - Higher-level threading interfaces.} -\declaremodule{standard}{threading} + Higher-level threading interface} -\modulesynopsis{Higher-level threading interfaces.} +\declaremodule{standard}{threading} +\modulesynopsis{Higher-level threading interface.} This module constructs higher-level threading interfaces on top of the @@ -85,7 +85,8 @@ module-level functions. All of the methods described below are executed atomically. -\subsection{Lock Objects} + +\subsection{Lock Objects \label{lock-objects}} A primitive lock is a synchronization primitive that is not owned by a particular thread when locked. In Python, it is currently @@ -109,7 +110,7 @@ and may vary across implementations. All methods are executed atomically. -\begin{methoddesc}{acquire}{blocking=1} +\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}} Acquire a lock, blocking or non-blocking. When invoked without arguments, block until the lock is @@ -137,7 +138,8 @@ Do not call this method when the lock is unlocked. There is no return value. \end{methoddesc} -\subsection{RLock Objects} + +\subsection{RLock Objects \label{rlock-objects}} A reentrant lock is a synchronization primitive that may be acquired multiple times by the same thread. Internally, it uses @@ -153,7 +155,7 @@ may be nested; only the final \method{release()} (i.e. the \method{release()} of outermost pair) resets the lock to unlocked and allows another thread blocked in \method{acquire()} to proceed. -\begin{methoddesc}{acquire}{blocking=1} +\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}} Acquire a lock, blocking or non-blocking. When invoked without arguments: if this thread already owns @@ -189,7 +191,8 @@ Do not call this method when the lock is unlocked. There is no return value. \end{methoddesc} -\subsection{Condition Objects} + +\subsection{Condition Objects \label{condition-objects}} A condition variable is always associated with some kind of lock; this can be passed in or one will be created by default. (Passing @@ -248,11 +251,11 @@ waiting threads. E.g. in a typical producer-consumer situation, adding one item to the buffer only needs to wake up one consumer thread. -\begin{classdesc}{Condition}{lock=None} -If the \var{lock} argument is given and not \code{None}, it must be a \class{Lock} -or \class{RLock} object, and it is used as the underlying lock. -Otherwise, a new \class{RLock} object is created and used as the -underlying lock. +\begin{classdesc}{Condition}{\optional{lock}} +If the \var{lock} argument is given and not \code{None}, it must be a +\class{Lock} or \class{RLock} object, and it is used as the underlying +lock. Otherwise, a new \class{RLock} object is created and used as +the underlying lock. \end{classdesc} \begin{methoddesc}{acquire}{*args} @@ -267,7 +270,7 @@ This method calls the corresponding method on the underlying lock; there is no return value. \end{methoddesc} -\begin{methoddesc}{wait}{timeout=None} +\begin{methoddesc}{wait}{\optional{timeout}} Wait until notified or until a timeout occurs. This must only be called when the calling thread has acquired the lock. @@ -278,17 +281,17 @@ same condition variable in another thread, or until the optional timeout occurs. Once awakened or timed out, it re-acquires the lock and returns. -When the timeout argument is present and not \code{None}, it should be a -floating point number specifying a timeout for the operation in -seconds (or fractions thereof). +When the \var{timeout} argument is present and not \code{None}, it +should be a floating point number specifying a timeout for the +operation in seconds (or fractions thereof). -When the underlying lock is an \class{RLock}, it is not released using its -\method{release()} method, since this may not actually unlock the lock -when it was acquired multiple times recursively. Instead, an -internal interface of the \class{RLock} 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. +When the underlying lock is an \class{RLock}, it is not released using +its \method{release()} method, since this may not actually unlock the +lock when it was acquired multiple times recursively. Instead, an +internal interface of the \class{RLock} 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. \end{methoddesc} \begin{methoddesc}{notify}{} @@ -314,12 +317,13 @@ Wake up all threads waiting on this condition. This method acts like \method{notify()}, but wakes up all waiting threads instead of one. \end{methoddesc} -\subsection{Semaphore Objects} + +\subsection{Semaphore Objects \label{semaphore-objects}} 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 \method{P()} and \method{V()} instead of \method{acquire()} -and \method{release()}). +Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of +\method{acquire()} and \method{release()}). A semaphore manages an internal counter which is decremented by each \method{acquire()} call and incremented by each \method{release()} @@ -327,12 +331,12 @@ call. The counter can never go below zero; when \method{acquire()} finds that it is zero, it blocks, waiting until some other thread calls \method{release()}. -\begin{classdesc}{Semaphore}{value=1} +\begin{classdesc}{Semaphore}{\optional{value}} The optional argument gives the initial value for the internal -counter; it defaults to 1. +counter; it defaults to \code{1}. \end{classdesc} -\begin{methoddesc}{acquire}{blocking=1} +\begin{methoddesc}{acquire}{\optional{blocking}} Acquire a semaphore. When invoked without arguments: if the internal counter is larger than @@ -345,13 +349,13 @@ 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. -When invoked with the \var{blocking} argument set to true, do the same -thing as when called without arguments, and return true. +When invoked with \var{blocking} set to true, do the same thing as +when called without arguments, and return true. -When invoked with the \var{blocking} argument 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. +When invoked with \var{blocking} 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. \end{methoddesc} \begin{methoddesc}{release}{} @@ -361,7 +365,8 @@ entry and another thread is waiting for it to become larger than zero again, wake up that thread. \end{methoddesc} -\subsection{Event Objects} + +\subsection{Event Objects \label{event-objects}} This is one of the simplest mechanisms for communication between threads: one thread signals an event and one or more other thread @@ -393,7 +398,7 @@ Subsequently, threads calling \method{wait()} will block until \method{set()} is called to set the internal flag to true again. \end{methoddesc} -\begin{methoddesc}{wait}{timeout=None} +\begin{methoddesc}{wait}{\optional{timeout}} Block until the internal flag is true. If the internal flag is true on entry, return immediately. Otherwise, block until another thread calls \method{set()} to set the flag to @@ -404,41 +409,42 @@ floating point number specifying a timeout for the operation in seconds (or fractions thereof). \end{methoddesc} -\subsection{Thread Objects} + +\subsection{Thread Objects \label{thread-objects}} This class represents an activity that is run in a separate thread of control. There are two ways to specify the activity: by passing a callable object to the constructor, or by overriding the \method{run()} method in a subclass. No other methods (except for the constructor) should be overridden in a subclass. In other words, -\emph{only} override the \method{__init__()} and \method{run()} methods of this class. - +\emph{only} override the \method{__init__()} and \method{run()} +methods of this class. Once a thread object is created, its activity must be started by -calling the thread's \method{start()} method. This invokes the \method{run()} -method in a separate thread of control. +calling the thread's \method{start()} method. This invokes the +\method{run()} method in a separate thread of control. Once the thread's activity is started, the thread is considered 'alive' and 'active' (these concepts are almost, but not quite exactly, the same; their definition is intentionally somewhat -vague). It stops being alive and active when its \method{run()} method -terminates -- either normally, or by raising an unhandled +vague). It stops being alive and active when its \method{run()} +method terminates -- either normally, or by raising an unhandled exception. The \method{isAlive()} method tests whether the thread is alive. -Other threads can call a thread's \method{join()} method. This blocks the -calling thread until the thread whose \method{join()} method is called -is terminated. +Other threads can call a thread's \method{join()} method. This blocks +the calling thread until the thread whose \method{join()} method is +called is terminated. A thread has a name. The name can be passed to the constructor, -set with the \method{setName()} method, and retrieved with the \method{getName()} -method. +set with the \method{setName()} method, and retrieved with the +\method{getName()} method. A thread can be flagged as a ``daemon thread''. The significance of this flag is that the entire Python program exits when only daemon threads are left. The initial value is inherited from the -creating thread. The flag can be set with the \method{setDaemon()} method -and retrieved with the \method{getDaemon()} method. +creating thread. The flag can be set with the \method{setDaemon()} +method and retrieved with the \method{getDaemon()} method. There is a ``main thread'' object; this corresponds to the initial thread of control in the Python program. It is not a @@ -449,38 +455,37 @@ created. These are thread objects corresponding to ``alien threads''. These are threads of control started outside the threading module, e.g. directly from C code. Dummy thread objects have limited functionality; they are always considered alive, -active, and daemonic, and cannot be \method{join()}ed. They are never +active, and daemonic, and cannot be \method{join()}ed. They are never deleted, since it is impossible to detect the termination of alien threads. \begin{classdesc}{Thread}{group=None, target=None, name=None, - args=(), kwargs={}} + args=(), kwargs=\{\}} This constructor should always be called with keyword arguments. Arguments are: -group -Should be None; reserved for future extension when a -ThreadGroup class is implemented. +\var{group} +Should be \code{None}; reserved for future extension when a +\class{ThreadGroup} class is implemented. -target +\var{target} Callable object to be invoked by the \method{run()} method. -Defaults to None, meaning nothing is called. +Defaults to \code{None}, meaning nothing is called. -name -The thread name. By default, a unique name is constructed -of the form ``Thread-N'' where N is a small decimal -number. +\var{name} +The thread name. By default, a unique name is constructed of the form +``Thread-\var{N}'' where \var{N} is a small decimal number. -args -Argument tuple for the target invocation. Defaults to (). +\var{args} +Argument tuple for the target invocation. Defaults to \code{()}. -kwargs +\var{kwargs} Keyword argument dictionary for the target invocation. -Defaults to {}. +Defaults to \code{\{\}}. If the subclass overrides the constructor, it must make sure -to invoke the base class constructor (Thread.__init__()) +to invoke the base class constructor (\code{Thread.__init__()}) before doing anything else to the thread. \end{classdesc} @@ -507,7 +512,7 @@ respectively. \end{methoddesc} -\begin{methoddesc}{join}{timeout=None} +\begin{methoddesc}{join}{\optional{timeout}} Wait until the thread terminates. This blocks the calling thread until the thread whose \method{join()} method is called terminates -- either normally or through an -- cgit v0.12