diff options
Diffstat (limited to 'Doc/lib/libthreading.tex')
| -rw-r--r-- | Doc/lib/libthreading.tex | 68 |
1 files changed, 32 insertions, 36 deletions
diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex index 0334750..522ea2f 100644 --- a/Doc/lib/libthreading.tex +++ b/Doc/lib/libthreading.tex @@ -15,17 +15,16 @@ situations where \module{threading} cannot be used because This module defines the following functions and objects: \begin{funcdesc}{activeCount}{} -Return the number of currently active \class{Thread} objects. -The returned count is equal to the length of the list returned by +Return the number of \class{Thread} objects currently alive. The +returned count is equal to the length of the list returned by \function{enumerate()}. -A function that returns the number of currently active threads. \end{funcdesc} -\begin{funcdesc}{Condition}{} +\begin{funcdescni}{Condition}{} A factory function that returns a new condition variable object. A condition variable allows one or more threads to wait until they are notified by another thread. -\end{funcdesc} +\end{funcdescni} \begin{funcdesc}{currentThread}{} Return the current \class{Thread} object, corresponding to the @@ -36,18 +35,18 @@ is returned. \end{funcdesc} \begin{funcdesc}{enumerate}{} -Return a list of all currently active \class{Thread} objects. -The list includes daemonic threads, dummy thread objects created -by \function{currentThread()}, and the main thread. It excludes terminated -threads and threads that have not yet been started. +Return a list of all \class{Thread} objects currently alive. The list +includes daemonic threads, dummy thread objects created by +\function{currentThread()}, and the main thread. It excludes +terminated threads and threads that have not yet been started. \end{funcdesc} -\begin{funcdesc}{Event}{} +\begin{funcdescni}{Event}{} A factory function that returns a new event object. An event manages a flag that can be set to true with the \method{set()} method and reset to false with the \method{clear()} method. The \method{wait()} method blocks until the flag is true. -\end{funcdesc} +\end{funcdescni} \begin{classdesc*}{local}{} A class that represents thread-local data. Thread-local data are data @@ -82,14 +81,14 @@ acquire it again without blocking; the thread must release it once for each time it has acquired it. \end{funcdesc} -\begin{funcdesc}{Semaphore}{\optional{value}} +\begin{funcdescni}{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} +\end{funcdescni} \begin{funcdesc}{BoundedSemaphore}{\optional{value}} A factory function that returns a new bounded semaphore object. A bounded @@ -100,12 +99,12 @@ 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}{} +\begin{classdesc*}{Thread} A class that represents a thread of control. This class can be safely subclassed in a limited fashion. \end{classdesc*} -\begin{classdesc*}{Timer}{} +\begin{classdesc*}{Timer} A thread that executes a function after a specified interval has passed. \end{classdesc*} @@ -183,7 +182,7 @@ and may vary across implementations. All methods are executed atomically. -\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}} +\begin{methoddesc}[Lock]{acquire}{\optional{blocking\code{ = 1}}} Acquire a lock, blocking or non-blocking. When invoked without arguments, block until the lock is @@ -198,7 +197,7 @@ immediately; otherwise, do the same thing as when called without arguments, and return true. \end{methoddesc} -\begin{methoddesc}{release}{} +\begin{methoddesc}[Lock]{release}{} Release a lock. When the lock is locked, reset it to unlocked, and return. If @@ -228,7 +227,7 @@ the final \method{release()} (the \method{release()} of the outermost pair) resets the lock to unlocked and allows another thread blocked in \method{acquire()} to proceed. -\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}} +\begin{methoddesc}[RLock]{acquire}{\optional{blocking\code{ = 1}}} Acquire a lock, blocking or non-blocking. When invoked without arguments: if this thread already owns @@ -250,7 +249,7 @@ immediately; otherwise, do the same thing as when called without arguments, and return true. \end{methoddesc} -\begin{methoddesc}{release}{} +\begin{methoddesc}[RLock]{release}{} Release a lock, decrementing the recursion level. If after the decrement it is zero, reset the lock to unlocked (not owned by any thread), and if any other threads are blocked waiting for the lock to @@ -526,12 +525,9 @@ 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 -exception. The \method{isAlive()} method tests whether the thread is -alive. +'alive'. It stops being alive 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 @@ -551,14 +547,13 @@ There is a ``main thread'' object; this corresponds to the initial thread of control in the Python program. It is not a daemon thread. -There is the possibility that ``dummy thread objects'' are -created. These are thread objects corresponding to ``alien -threads''. These are threads of control started outside the -threading module, such as 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 -deleted, since it is impossible to detect the termination of alien -threads. +There is the possibility that ``dummy thread objects'' are created. +These are thread objects corresponding to ``alien threads'', which +are threads of control started outside the threading module, such as +directly from C code. Dummy thread objects have limited +functionality; they are always considered alive 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, @@ -646,7 +641,8 @@ name. The initial name is set by the constructor. Return whether the thread is alive. Roughly, a thread is alive from the moment the \method{start()} method -returns until its \method{run()} method terminates. +returns until its \method{run()} method terminates. The module +function \function{enumerate()} returns a list of all alive threads. \end{methoddesc} \begin{methoddesc}{isDaemon}{} @@ -659,8 +655,8 @@ This must be called before \method{start()} is called. The initial value is inherited from the creating thread. -The entire Python program exits when no active non-daemon -threads are left. +The entire Python program exits when no alive non-daemon threads are +left. \end{methoddesc} |