mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-03 11:23:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Fixed tons of small markup problems.

Browse source
This commit is contained in:
Fred Drake 1999-03-12 19:57:38 +00:00
parent 3fce883922
commit bf5a6d2eb4
1 changed files with 74 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

141
Doc/lib/libthreading.tex
View file

@ -1,8 +1,8 @@
\section{\module{threading} --- \section{\module{threading} ---
Higher-level threading interfaces.} Higher-level threading interface}
\declaremodule{standard}{threading}
\modulesynopsis{Higher-level threading interfaces.} \declaremodule{standard}{threading}
\modulesynopsis{Higher-level threading interface.}
This module constructs higher-level threading interfaces on top of the 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. 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 A primitive lock is a synchronization primitive that is not owned
by a particular thread when locked. In Python, it is currently 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. All methods are executed atomically.
\begin{methoddesc}{acquire}{blocking=1} \begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
Acquire a lock, blocking or non-blocking. Acquire a lock, blocking or non-blocking.
When invoked without arguments, block until the lock is 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. There is no return value.
\end{methoddesc} \end{methoddesc}
\subsection{RLock Objects}
\subsection{RLock Objects \label{rlock-objects}}
A reentrant lock is a synchronization primitive that may be A reentrant lock is a synchronization primitive that may be
acquired multiple times by the same thread. Internally, it uses 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 outermost pair) resets the lock to unlocked and allows another
thread blocked in \method{acquire()} to proceed. 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. Acquire a lock, blocking or non-blocking.
When invoked without arguments: if this thread already owns 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. There is no return value.
\end{methoddesc} \end{methoddesc}
\subsection{Condition Objects}
\subsection{Condition Objects \label{condition-objects}}
A condition variable is always associated with some kind of lock; A condition variable is always associated with some kind of lock;
this can be passed in or one will be created by default. (Passing 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 adding one item to the buffer only needs to wake up one consumer
thread. thread.
\begin{classdesc}{Condition}{lock=None} \begin{classdesc}{Condition}{\optional{lock}}
If the \var{lock} argument is given and not \code{None}, it must be a \class{Lock} If the \var{lock} argument is given and not \code{None}, it must be a
or \class{RLock} object, and it is used as the underlying lock. \class{Lock} or \class{RLock} object, and it is used as the underlying
Otherwise, a new \class{RLock} object is created and used as the lock. Otherwise, a new \class{RLock} object is created and used as
underlying lock. the underlying lock.
\end{classdesc} \end{classdesc}
\begin{methoddesc}{acquire}{*args} \begin{methoddesc}{acquire}{*args}
@ -267,7 +270,7 @@ This method calls the corresponding method on the underlying
lock; there is no return value. lock; there is no return value.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{wait}{timeout=None} \begin{methoddesc}{wait}{\optional{timeout}}
Wait until notified or until a timeout occurs. Wait until notified or until a timeout occurs.
This must only be called when the calling thread has acquired the This must only be called when the calling thread has acquired the
lock. 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 timeout occurs. Once awakened or timed out, it re-acquires the lock
and returns. and returns.
When the timeout argument is present and not \code{None}, it should be a When the \var{timeout} argument is present and not \code{None}, it
floating point number specifying a timeout for the operation in should be a floating point number specifying a timeout for the
seconds (or fractions thereof). operation in seconds (or fractions thereof).
When the underlying lock is an \class{RLock}, it is not released using its When the underlying lock is an \class{RLock}, it is not released using
\method{release()} method, since this may not actually unlock the lock its \method{release()} method, since this may not actually unlock the
when it was acquired multiple times recursively. Instead, an lock when it was acquired multiple times recursively. Instead, an
internal interface of the \class{RLock} class is used, which really unlocks it internal interface of the \class{RLock} class is used, which really
even when it has been recursively acquired several times. Another unlocks it even when it has been recursively acquired several times.
internal interface is then used to restore the recursion level when Another internal interface is then used to restore the recursion level
the lock is reacquired. when the lock is reacquired.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{notify}{} \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. \method{notify()}, but wakes up all waiting threads instead of one.
\end{methoddesc} \end{methoddesc}
\subsection{Semaphore Objects}
\subsection{Semaphore Objects \label{semaphore-objects}}
This is one of the oldest synchronization primitives in the history of This is one of the oldest synchronization primitives in the history of
computer science, invented by the early Dutch computer scientist computer science, invented by the early Dutch computer scientist
Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of \method{acquire()} Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of
and \method{release()}). \method{acquire()} and \method{release()}).
A semaphore manages an internal counter which is decremented by each A semaphore manages an internal counter which is decremented by each
\method{acquire()} call and incremented by each \method{release()} \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 finds that it is zero, it blocks, waiting until some other thread
calls \method{release()}. calls \method{release()}.
\begin{classdesc}{Semaphore}{value=1} \begin{classdesc}{Semaphore}{\optional{value}}
The optional argument gives the initial value for the internal The optional argument gives the initial value for the internal
counter; it defaults to 1. counter; it defaults to \code{1}.
\end{classdesc} \end{classdesc}
\begin{methoddesc}{acquire}{blocking=1} \begin{methoddesc}{acquire}{\optional{blocking}}
Acquire a semaphore. Acquire a semaphore.
When invoked without arguments: if the internal counter is larger than 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 threads are awakened should not be relied on. There is no return
value in this case. value in this case.
When invoked with the \var{blocking} argument set to true, do the same When invoked with \var{blocking} set to true, do the same thing as
thing as when called without arguments, and return true. when called without arguments, and return true.
When invoked with the \var{blocking} argument set to false, do not When invoked with \var{blocking} set to false, do not block. If a
block. If a call without an argument would block, return false call without an argument would block, return false immediately;
immediately; otherwise, do the same thing as when called without otherwise, do the same thing as when called without arguments, and
arguments, and return true. return true.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{release}{} \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. than zero again, wake up that thread.
\end{methoddesc} \end{methoddesc}
\subsection{Event Objects}
\subsection{Event Objects \label{event-objects}}
This is one of the simplest mechanisms for communication between This is one of the simplest mechanisms for communication between
threads: one thread signals an event and one or more other thread 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. called to set the internal flag to true again.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{wait}{timeout=None} \begin{methoddesc}{wait}{\optional{timeout}}
Block until the internal flag is true. Block until the internal flag is true.
If the internal flag is true on entry, return immediately. Otherwise, If the internal flag is true on entry, return immediately. Otherwise,
block until another thread calls \method{set()} to set the flag to 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). seconds (or fractions thereof).
\end{methoddesc} \end{methoddesc}
\subsection{Thread Objects}
\subsection{Thread Objects \label{thread-objects}}
This class represents an activity that is run in a separate thread This class represents an activity that is run in a separate thread
of control. There are two ways to specify the activity: by of control. There are two ways to specify the activity: by
passing a callable object to the constructor, or by overriding the passing a callable object to the constructor, or by overriding the
\method{run()} method in a subclass. No other methods (except for the \method{run()} method in a subclass. No other methods (except for the
constructor) should be overridden in a subclass. In other words, 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 Once a thread object is created, its activity must be started by
calling the thread's \method{start()} method. This invokes the \method{run()} calling the thread's \method{start()} method. This invokes the
method in a separate thread of control. \method{run()} method in a separate thread of control.
Once the thread's activity is started, the thread is considered Once the thread's activity is started, the thread is considered
'alive' and 'active' (these concepts are almost, but not quite 'alive' and 'active' (these concepts are almost, but not quite
exactly, the same; their definition is intentionally somewhat exactly, the same; their definition is intentionally somewhat
vague). It stops being alive and active when its \method{run()} method vague). It stops being alive and active when its \method{run()}
terminates -- either normally, or by raising an unhandled method terminates -- either normally, or by raising an unhandled
exception. The \method{isAlive()} method tests whether the thread is exception. The \method{isAlive()} method tests whether the thread is
alive. alive.
Other threads can call a thread's \method{join()} method. This blocks the Other threads can call a thread's \method{join()} method. This blocks
calling thread until the thread whose \method{join()} method is called the calling thread until the thread whose \method{join()} method is
is terminated. called is terminated.
A thread has a name. The name can be passed to the constructor, 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()} set with the \method{setName()} method, and retrieved with the
method. \method{getName()} method.
A thread can be flagged as a ``daemon thread''. The significance A thread can be flagged as a ``daemon thread''. The significance
of this flag is that the entire Python program exits when only of this flag is that the entire Python program exits when only
daemon threads are left. The initial value is inherited from the daemon threads are left. The initial value is inherited from the
creating thread. The flag can be set with the \method{setDaemon()} method creating thread. The flag can be set with the \method{setDaemon()}
and retrieved with the \method{getDaemon()} method. method and retrieved with the \method{getDaemon()} method.
There is a ``main thread'' object; this corresponds to the There is a ``main thread'' object; this corresponds to the
initial thread of control in the Python program. It is not a initial thread of control in the Python program. It is not a
@ -455,32 +461,31 @@ threads.
\begin{classdesc}{Thread}{group=None, target=None, name=None, \begin{classdesc}{Thread}{group=None, target=None, name=None,
args=(), kwargs={}} args=(), kwargs=\{\}}
This constructor should always be called with keyword This constructor should always be called with keyword
arguments. Arguments are: arguments. Arguments are:
group \var{group}
Should be None; reserved for future extension when a Should be \code{None}; reserved for future extension when a
ThreadGroup class is implemented. \class{ThreadGroup} class is implemented.
target \var{target}
Callable object to be invoked by the \method{run()} method. 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 \var{name}
The thread name. By default, a unique name is constructed The thread name. By default, a unique name is constructed of the form
of the form ``Thread-N'' where N is a small decimal ``Thread-\var{N}'' where \var{N} is a small decimal number.
number.
args \var{args}
Argument tuple for the target invocation. Defaults to (). Argument tuple for the target invocation. Defaults to \code{()}.
kwargs \var{kwargs}
Keyword argument dictionary for the target invocation. Keyword argument dictionary for the target invocation.
Defaults to {}. Defaults to \code{\{\}}.
If the subclass overrides the constructor, it must make sure 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. before doing anything else to the thread.
\end{classdesc} \end{classdesc}
@ -507,7 +512,7 @@ respectively.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{join}{timeout=None} \begin{methoddesc}{join}{\optional{timeout}}
Wait until the thread terminates. Wait until the thread terminates.
This blocks the calling thread until the thread whose \method{join()} This blocks the calling thread until the thread whose \method{join()}
method is called terminates -- either normally or through an method is called terminates -- either normally or through an