summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorFred Drake <fdrake@acm.org>1999-03-12 19:57:38 (GMT)
committerFred Drake <fdrake@acm.org>1999-03-12 19:57:38 (GMT)
commitbf5a6d2eb4664f6508a74e7890abe6b07504e6b0 (patch)
tree12248903ce16abda7113247d6d68a45b35ca0e7e /Doc
parent3fce8839223bf387257f3fd30545d796ba38f1fe (diff)
downloadcpython-bf5a6d2eb4664f6508a74e7890abe6b07504e6b0.zip
cpython-bf5a6d2eb4664f6508a74e7890abe6b07504e6b0.tar.gz
cpython-bf5a6d2eb4664f6508a74e7890abe6b07504e6b0.tar.bz2
Fixed tons of small markup problems.
Diffstat (limited to 'Doc')
-rw-r--r--Doc/lib/libthreading.tex143
1 files 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