traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Fixed tons of small markup problems.

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
Doc/lib/libthreading.tex
View File

@ -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