cpython-lru_cache-weakref: Doc/lib/libthreading.tex annotate

annotate Doc/lib/libthreading.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.

author	Fred Drake <fdrake@acm.org>
date	Tue, 18 Dec 2001 16:31:08 +0000
parents	f3036d4e3c22
children	4a4597bc4ea2

rev	line source
8918 acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8767 diff changeset	1 \section{\module{threading} ---
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	2 Higher-level threading interface}
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	3
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8683 diff changeset	4 \declaremodule{standard}{threading}
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	5 \modulesynopsis{Higher-level threading interface.}
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8683 diff changeset	6
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	7
8767 8434e9d00b5a Fix the synopsis. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	8 This module constructs higher-level threading interfaces on top of the
10703 e4e800a78d8d Make internal module references hyperlinks wherever it makes sense. Fred Drake <fdrake@acm.org> parents: 10392 diff changeset	9 lower level \refmodule{thread} module.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	10
8767 8434e9d00b5a Fix the synopsis. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	11 This module is safe for use with \samp{from threading import *}. It
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	12 defines the following functions and objects:
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	13
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	14 \begin{funcdesc}{activeCount}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	15 Return the number of currently active \class{Thread} objects.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	16 The returned count is equal to the length of the list returned by
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	17 \function{enumerate()}.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	18 A function that returns the number of currently active threads.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	19 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	20
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	21 \begin{funcdesc}{Condition}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	22 A factory function that returns a new condition variable object.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	23 A condition variable allows one or more threads to wait until they
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	24 are notified by another thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	25 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	26
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	27 \begin{funcdesc}{currentThread}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	28 Return the current \class{Thread} object, corresponding to the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	29 caller's thread of control. If the caller's thread of control was not
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	30 created through the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	31 \module{threading} module, a dummy thread object with limited functionality
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	32 is returned.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	33 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	34
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	35 \begin{funcdesc}{enumerate}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	36 Return a list of all currently active \class{Thread} objects.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	37 The list includes daemonic threads, dummy thread objects created
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	38 by \function{currentThread()}, and the main thread. It excludes terminated
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	39 threads and threads that have not yet been started.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	40 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	41
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	42 \begin{funcdesc}{Event}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	43 A factory function that returns a new event object. An event
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	44 manages a flag that can be set to true with the \method{set()} method and
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	45 reset to false with the \method{clear()} method. The \method{wait()} method blocks
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	46 until the flag is true.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	47 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	48
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	49 \begin{funcdesc}{Lock}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	50 A factory function that returns a new primitive lock object. Once
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	51 a thread has acquired it, subsequent attempts to acquire it block,
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	52 until it is released; any thread may release it.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	53 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	54
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	55 \begin{funcdesc}{RLock}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	56 A factory function that returns a new reentrant lock object.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	57 A reentrant lock must be released by the thread that acquired it.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	58 Once a thread has acquired a reentrant lock, the same thread may
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	59 acquire it again without blocking; the thread must release it once
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	60 for each time it has acquired it.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	61 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	62
19400 be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	63 \begin{funcdesc}{Semaphore}{\optional{value}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	64 A factory function that returns a new semaphore object. A
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	65 semaphore manages a counter representing the number of \method{release()}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	66 calls minus the number of \method{acquire()} calls, plus an initial value.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	67 The \method{acquire()} method blocks if necessary until it can return
19400 be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	68 without making the counter negative. If not given, \var{value} defaults to
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	69 1.
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	70 \end{funcdesc}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	71
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	72 \begin{funcdesc}{BoundedSemaphore}{\optional{value}}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	73 A factory function that returns a new bounded semaphore object. A bounded
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	74 semaphore checks to make sure its current value doesn't exceed its initial
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	75 value. If it does, \exception{ValueError} is raised. In most situations
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	76 semaphores are used to guard resources with limited capacity. If the
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	77 semaphore is released too many times it's a sign of a bug. If not given,
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	78 \var{value} defaults to 1.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	79 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	80
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	81 \begin{classdesc*}{Thread}{}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	82 A class that represents a thread of control. This class can be safely subclassed in a limited fashion.
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	83 \end{classdesc*}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	84
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	85 \begin{classdesc*}{Timer}{}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	86 A thread that executes a function after a specified interval has passed.
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	87 \end{classdesc*}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	88
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	89 Detailed interfaces for the objects are documented below.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	90
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	91 The design of this module is loosely based on Java's threading model.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	92 However, where Java makes locks and condition variables basic behavior
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	93 of every object, they are separate objects in Python. Python's \class{Thread}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	94 class supports a subset of the behavior of Java's Thread class;
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	95 currently, there are no priorities, no thread groups, and threads
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	96 cannot be destroyed, stopped, suspended, resumed, or interrupted. The
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	97 static methods of Java's Thread class, when implemented, are mapped to
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	98 module-level functions.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	99
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	100 All of the methods described below are executed atomically.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	101
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	102
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	103 \subsection{Lock Objects \label{lock-objects}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	104
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	105 A primitive lock is a synchronization primitive that is not owned
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	106 by a particular thread when locked. In Python, it is currently
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	107 the lowest level synchronization primitive available, implemented
10703 e4e800a78d8d Make internal module references hyperlinks wherever it makes sense. Fred Drake <fdrake@acm.org> parents: 10392 diff changeset	108 directly by the \refmodule{thread} extension module.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	109
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	110 A primitive lock is in one of two states, ``locked'' or ``unlocked''.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	111 It is created in the unlocked state. It has two basic methods,
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	112 \method{acquire()} and \method{release()}. When the state is
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	113 unlocked, \method{acquire()} changes the state to locked and returns
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	114 immediately. When the state is locked, \method{acquire()} blocks
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	115 until a call to \method{release()} in another thread changes it to
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	116 unlocked, then the \method{acquire()} call resets it to locked and
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	117 returns. The \method{release()} method should only be called in the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	118 locked state; it changes the state to unlocked and returns
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	119 immediately. When more than one thread is blocked in
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	120 \method{acquire()} waiting for the state to turn to unlocked, only one
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	121 thread proceeds when a \method{release()} call resets the state to
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	122 unlocked; which one of the waiting threads proceeds is not defined,
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	123 and may vary across implementations.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	124
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	125 All methods are executed atomically.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	126
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	127 \begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	128 Acquire a lock, blocking or non-blocking.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	129
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	130 When invoked without arguments, block until the lock is
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	131 unlocked, then set it to locked, and return. There is no
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	132 return value in this case.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	133
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	134 When invoked with the \var{blocking} argument set to true, do the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	135 same thing as when called without arguments, and return true.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	136
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	137 When invoked with the \var{blocking} argument set to false, do not
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	138 block. If a call without an argument would block, return false
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	139 immediately; otherwise, do the same thing as when called
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	140 without arguments, and return true.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	141 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	142
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	143 \begin{methoddesc}{release}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	144 Release a lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	145
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	146 When the lock is locked, reset it to unlocked, and return. If
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	147 any other threads are blocked waiting for the lock to become
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	148 unlocked, allow exactly one of them to proceed.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	149
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	150 Do not call this method when the lock is unlocked.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	151
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	152 There is no return value.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	153 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	154
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	155
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	156 \subsection{RLock Objects \label{rlock-objects}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	157
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	158 A reentrant lock is a synchronization primitive that may be
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	159 acquired multiple times by the same thread. Internally, it uses
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	160 the concepts of ``owning thread'' and ``recursion level'' in
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	161 addition to the locked/unlocked state used by primitive locks. In
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	162 the locked state, some thread owns the lock; in the unlocked
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	163 state, no thread owns it.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	164
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	165 To lock the lock, a thread calls its \method{acquire()} method; this
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	166 returns once the thread owns the lock. To unlock the lock, a
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18009 diff changeset	167 thread calls its \method{release()} method.
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18009 diff changeset	168 \method{acquire()}/\method{release()} call pairs may be nested; only
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18009 diff changeset	169 the final \method{release()} (the \method{release()} of the outermost
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18009 diff changeset	170 pair) resets the lock to unlocked and allows another thread blocked in
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18009 diff changeset	171 \method{acquire()} to proceed.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	172
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	173 \begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	174 Acquire a lock, blocking or non-blocking.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	175
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	176 When invoked without arguments: if this thread already owns
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	177 the lock, increment the recursion level by one, and return
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	178 immediately. Otherwise, if another thread owns the lock,
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	179 block until the lock is unlocked. Once the lock is unlocked
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	180 (not owned by any thread), then grab ownership, set the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	181 recursion level to one, and return. If more than one thread
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	182 is blocked waiting until the lock is unlocked, only one at a
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	183 time will be able to grab ownership of the lock. There is no
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	184 return value in this case.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	185
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	186 When invoked with the \var{blocking} argument set to true, do the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	187 same thing as when called without arguments, and return true.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	188
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	189 When invoked with the \var{blocking} argument set to false, do not
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	190 block. If a call without an argument would block, return false
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	191 immediately; otherwise, do the same thing as when called
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	192 without arguments, and return true.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	193 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	194
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	195 \begin{methoddesc}{release}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	196 Release a lock, decrementing the recursion level. If after the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	197 decrement it is zero, reset the lock to unlocked (not owned by any
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	198 thread), and if any other threads are blocked waiting for the lock to
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	199 become unlocked, allow exactly one of them to proceed. If after the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	200 decrement the recursion level is still nonzero, the lock remains
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	201 locked and owned by the calling thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	202
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	203 Only call this method when the calling thread owns the lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	204 Do not call this method when the lock is unlocked.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	205
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	206 There is no return value.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	207 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	208
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	209
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	210 \subsection{Condition Objects \label{condition-objects}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	211
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	212 A condition variable is always associated with some kind of lock;
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	213 this can be passed in or one will be created by default. (Passing
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	214 one in is useful when several condition variables must share the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	215 same lock.)
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	216
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	217 A condition variable has \method{acquire()} and \method{release()}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	218 methods that call the corresponding methods of the associated lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	219 It also has a \method{wait()} method, and \method{notify()} and
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	220 \method{notifyAll()} methods. These three must only be called when
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	221 the calling thread has acquired the lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	222
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	223 The \method{wait()} method releases the lock, and then blocks until it
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	224 is awakened by a \method{notify()} or \method{notifyAll()} call for
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	225 the same condition variable in another thread. Once awakened, it
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	226 re-acquires the lock and returns. It is also possible to specify a
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	227 timeout.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	228
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	229 The \method{notify()} method wakes up one of the threads waiting for
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	230 the condition variable, if any are waiting. The \method{notifyAll()}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	231 method wakes up all threads waiting for the condition variable.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	232
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	233 Note: the \method{notify()} and \method{notifyAll()} methods don't
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	234 release the lock; this means that the thread or threads awakened will
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	235 not return from their \method{wait()} call immediately, but only when
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	236 the thread that called \method{notify()} or \method{notifyAll()}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	237 finally relinquishes ownership of the lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	238
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	239 Tip: the typical programming style using condition variables uses the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	240 lock to synchronize access to some shared state; threads that are
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	241 interested in a particular change of state call \method{wait()}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	242 repeatedly until they see the desired state, while threads that modify
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	243 the state call \method{notify()} or \method{notifyAll()} when they
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	244 change the state in such a way that it could possibly be a desired
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	245 state for one of the waiters. For example, the following code is a
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	246 generic producer-consumer situation with unlimited buffer capacity:
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	247
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	248 \begin{verbatim}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	249 # Consume one item
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	250 cv.acquire()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	251 while not an_item_is_available():
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	252 cv.wait()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	253 get_an_available_item()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	254 cv.release()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	255
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	256 # Produce one item
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	257 cv.acquire()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	258 make_an_item_available()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	259 cv.notify()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	260 cv.release()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	261 \end{verbatim}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	262
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	263 To choose between \method{notify()} and \method{notifyAll()}, consider
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	264 whether one state change can be interesting for only one or several
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	265 waiting threads. E.g. in a typical producer-consumer situation,
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	266 adding one item to the buffer only needs to wake up one consumer
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	267 thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	268
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	269 \begin{classdesc}{Condition}{\optional{lock}}
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	270 If the \var{lock} argument is given and not \code{None}, it must be a
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	271 \class{Lock} or \class{RLock} object, and it is used as the underlying
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	272 lock. Otherwise, a new \class{RLock} object is created and used as
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	273 the underlying lock.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	274 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	275
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	276 \begin{methoddesc}{acquire}{*args}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	277 Acquire the underlying lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	278 This method calls the corresponding method on the underlying
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	279 lock; the return value is whatever that method returns.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	280 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	281
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	282 \begin{methoddesc}{release}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	283 Release the underlying lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	284 This method calls the corresponding method on the underlying
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	285 lock; there is no return value.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	286 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	287
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	288 \begin{methoddesc}{wait}{\optional{timeout}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	289 Wait until notified or until a timeout occurs.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	290 This must only be called when the calling thread has acquired the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	291 lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	292
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	293 This method releases the underlying lock, and then blocks until it is
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	294 awakened by a \method{notify()} or \method{notifyAll()} call for the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	295 same condition variable in another thread, or until the optional
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	296 timeout occurs. Once awakened or timed out, it re-acquires the lock
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	297 and returns.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	298
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	299 When the \var{timeout} argument is present and not \code{None}, it
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	300 should be a floating point number specifying a timeout for the
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	301 operation in seconds (or fractions thereof).
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	302
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	303 When the underlying lock is an \class{RLock}, it is not released using
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	304 its \method{release()} method, since this may not actually unlock the
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	305 lock when it was acquired multiple times recursively. Instead, an
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	306 internal interface of the \class{RLock} class is used, which really
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	307 unlocks it even when it has been recursively acquired several times.
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	308 Another internal interface is then used to restore the recursion level
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	309 when the lock is reacquired.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	310 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	311
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	312 \begin{methoddesc}{notify}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	313 Wake up a thread waiting on this condition, if any.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	314 This must only be called when the calling thread has acquired the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	315 lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	316
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	317 This method wakes up one of the threads waiting for the condition
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	318 variable, if any are waiting; it is a no-op if no threads are waiting.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	319
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	320 The current implementation wakes up exactly one thread, if any are
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	321 waiting. However, it's not safe to rely on this behavior. A future,
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	322 optimized implementation may occasionally wake up more than one
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	323 thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	324
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	325 Note: the awakened thread does not actually return from its
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	326 \method{wait()} call until it can reacquire the lock. Since
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	327 \method{notify()} does not release the lock, its caller should.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	328 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	329
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	330 \begin{methoddesc}{notifyAll}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	331 Wake up all threads waiting on this condition. This method acts like
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	332 \method{notify()}, but wakes up all waiting threads instead of one.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	333 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	334
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	335
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	336 \subsection{Semaphore Objects \label{semaphore-objects}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	337
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	338 This is one of the oldest synchronization primitives in the history of
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	339 computer science, invented by the early Dutch computer scientist
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	340 Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	341 \method{acquire()} and \method{release()}).
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	342
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	343 A semaphore manages an internal counter which is decremented by each
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	344 \method{acquire()} call and incremented by each \method{release()}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	345 call. The counter can never go below zero; when \method{acquire()}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	346 finds that it is zero, it blocks, waiting until some other thread
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	347 calls \method{release()}.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	348
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	349 \begin{classdesc}{Semaphore}{\optional{value}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	350 The optional argument gives the initial value for the internal
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	351 counter; it defaults to \code{1}.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	352 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	353
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	354 \begin{methoddesc}{acquire}{\optional{blocking}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	355 Acquire a semaphore.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	356
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	357 When invoked without arguments: if the internal counter is larger than
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	358 zero on entry, decrement it by one and return immediately. If it is
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	359 zero on entry, block, waiting until some other thread has called
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	360 \method{release()} to make it larger than zero. This is done with
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	361 proper interlocking so that if multiple \method{acquire()} calls are
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	362 blocked, \method{release()} will wake exactly one of them up. The
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	363 implementation may pick one at random, so the order in which blocked
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	364 threads are awakened should not be relied on. There is no return
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	365 value in this case.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	366
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	367 When invoked with \var{blocking} set to true, do the same thing as
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	368 when called without arguments, and return true.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	369
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	370 When invoked with \var{blocking} set to false, do not block. If a
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	371 call without an argument would block, return false immediately;
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	372 otherwise, do the same thing as when called without arguments, and
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	373 return true.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	374 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	375
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	376 \begin{methoddesc}{release}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	377 Release a semaphore,
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	378 incrementing the internal counter by one. When it was zero on
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	379 entry and another thread is waiting for it to become larger
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	380 than zero again, wake up that thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	381 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	382
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	383
19400 be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	384 \subsubsection{\class{Semaphore} Example \label{semaphore-examples}}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	385
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	386 Semaphores are often used to guard resources with limited capacity, for
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	387 example, a database server. In any situation where the size of the resource
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	388 size is fixed, you should use a bounded semaphore. Before spawning any
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	389 worker threads, your main thread would initialize the semaphore:
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	390
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	391 \begin{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	392 maxconnections = 5
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	393 ...
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	394 pool_sema = BoundedSemaphore(value=maxconnections)
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	395 \end{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	396
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	397 Once spawned, worker threads call the semaphore's acquire and release
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	398 methods when they need to connect to the server:
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	399
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	400 \begin{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	401 pool_sema.acquire()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	402 conn = connectdb()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	403 ... use connection ...
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	404 conn.close()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	405 pool_sema.release()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	406 \end{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	407
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	408 The use of a bounded semaphore reduces the chance that a programming error
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	409 which causes the semaphore to be released more than it's acquired will go
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	410 undetected.
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	411
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	412 \subsection{Event Objects \label{event-objects}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	413
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	414 This is one of the simplest mechanisms for communication between
10730 c5f449aa4345 Fix a grammatical error reported by Detlef Lannert Fred Drake <fdrake@acm.org> parents: 10703 diff changeset	415 threads: one thread signals an event and one or more other threads
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	416 are waiting for it.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	417
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	418 An event object manages an internal flag that can be set to true with
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	419 the \method{set()} method and reset to false with the \method{clear()} method. The
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	420 \method{wait()} method blocks until the flag is true.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	421
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	422
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	423 \begin{classdesc}{Event}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	424 The internal flag is initially false.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	425 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	426
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	427 \begin{methoddesc}{isSet}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	428 Return true if and only if the internal flag is true.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	429 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	430
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	431 \begin{methoddesc}{set}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	432 Set the internal flag to true.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	433 All threads waiting for it to become true are awakened.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	434 Threads that call \method{wait()} once the flag is true will not block
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	435 at all.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	436 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	437
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	438 \begin{methoddesc}{clear}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	439 Reset the internal flag to false.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	440 Subsequently, threads calling \method{wait()} will block until \method{set()} is
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	441 called to set the internal flag to true again.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	442 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	443
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	444 \begin{methoddesc}{wait}{\optional{timeout}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	445 Block until the internal flag is true.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	446 If the internal flag is true on entry, return immediately. Otherwise,
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	447 block until another thread calls \method{set()} to set the flag to
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	448 true, or until the optional timeout occurs.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	449
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	450 When the timeout argument is present and not \code{None}, it should be a
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	451 floating point number specifying a timeout for the operation in
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	452 seconds (or fractions thereof).
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	453 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	454
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	455
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	456 \subsection{Thread Objects \label{thread-objects}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	457
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	458 This class represents an activity that is run in a separate thread
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	459 of control. There are two ways to specify the activity: by
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	460 passing a callable object to the constructor, or by overriding the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	461 \method{run()} method in a subclass. No other methods (except for the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	462 constructor) should be overridden in a subclass. In other words,
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	463 \emph{only} override the \method{__init__()} and \method{run()}
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	464 methods of this class.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	465
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	466 Once a thread object is created, its activity must be started by
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	467 calling the thread's \method{start()} method. This invokes the
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	468 \method{run()} method in a separate thread of control.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	469
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	470 Once the thread's activity is started, the thread is considered
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	471 'alive' and 'active' (these concepts are almost, but not quite
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	472 exactly, the same; their definition is intentionally somewhat
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	473 vague). It stops being alive and active when its \method{run()}
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	474 method terminates -- either normally, or by raising an unhandled
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	475 exception. The \method{isAlive()} method tests whether the thread is
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	476 alive.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	477
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	478 Other threads can call a thread's \method{join()} method. This blocks
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	479 the calling thread until the thread whose \method{join()} method is
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	480 called is terminated.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	481
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	482 A thread has a name. The name can be passed to the constructor,
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	483 set with the \method{setName()} method, and retrieved with the
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	484 \method{getName()} method.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	485
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	486 A thread can be flagged as a ``daemon thread''. The significance
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	487 of this flag is that the entire Python program exits when only
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	488 daemon threads are left. The initial value is inherited from the
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	489 creating thread. The flag can be set with the \method{setDaemon()}
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	490 method and retrieved with the \method{isDaemon()} method.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	491
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	492 There is a ``main thread'' object; this corresponds to the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	493 initial thread of control in the Python program. It is not a
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	494 daemon thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	495
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	496 There is the possibility that ``dummy thread objects'' are
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	497 created. These are thread objects corresponding to ``alien
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	498 threads''. These are threads of control started outside the
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18009 diff changeset	499 threading module, such as directly from C code. Dummy thread objects
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	500 have limited functionality; they are always considered alive,
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	501 active, and daemonic, and cannot be \method{join()}ed. They are never
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	502 deleted, since it is impossible to detect the termination of alien
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	503 threads.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	504
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	505
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	506 \begin{classdesc}{Thread}{group=None, target=None, name=None,
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	507 args=(), kwargs=\{\}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	508 This constructor should always be called with keyword
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	509 arguments. Arguments are:
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	510
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	511 \var{group} should be \code{None}; reserved for future extension when
50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	512 a \class{ThreadGroup} class is implemented.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	513
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	514 \var{target} is the callable object to be invoked by the
50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	515 \method{run()} method. Defaults to \code{None}, meaning nothing is
50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	516 called.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	517
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	518 \var{name} is the thread name. By default, a unique name is
50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	519 constructed of the form ``Thread-\var{N}'' where \var{N} is a small
50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	520 decimal number.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	521
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	522 \var{args} is the argument tuple for the target invocation. Defaults
50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	523 to \code{()}.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	524
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	525 \var{kwargs} is a dictionary of keyword arguments for the target
50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	526 invocation. Defaults to \code{\{\}}.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	527
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	528 If the subclass overrides the constructor, it must make sure
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	529 to invoke the base class constructor (\code{Thread.__init__()})
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	530 before doing anything else to the thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	531 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	532
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	533 \begin{methoddesc}{start}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	534 Start the thread's activity.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	535
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	536 This must be called at most once per thread object. It
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	537 arranges for the object's \method{run()} method to be invoked in a
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	538 separate thread of control.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	539 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	540
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	541 \begin{methoddesc}{run}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	542 Method representing the thread's activity.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	543
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	544 You may override this method in a subclass. The standard
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	545 \method{run()} method invokes the callable object passed to the object's constructor as the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	546 \var{target} argument, if any, with sequential and keyword
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	547 arguments taken from the \var{args} and \var{kwargs} arguments,
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	548 respectively.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	549 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	550
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	551 \begin{methoddesc}{join}{\optional{timeout}}
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	552 Wait until the thread terminates.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	553 This blocks the calling thread until the thread whose \method{join()}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	554 method is called terminates -- either normally or through an
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	555 unhandled exception -- or until the optional timeout occurs.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	556
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	557 When the \var{timeout} argument is present and not \code{None}, it should
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	558 be a floating point number specifying a timeout for the
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	559 operation in seconds (or fractions thereof).
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	560
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	561 A thread can be \method{join()}ed many times.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	562
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	563 A thread cannot join itself because this would cause a
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	564 deadlock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	565
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	566 It is an error to attempt to \method{join()} a thread before it has
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	567 been started.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	568 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	569
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	570 \begin{methoddesc}{getName}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	571 Return the thread's name.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	572 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	573
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	574 \begin{methoddesc}{setName}{name}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	575 Set the thread's name.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	576
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	577 The name is a string used for identification purposes only.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	578 It has no semantics. Multiple threads may be given the same
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	579 name. The initial name is set by the constructor.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	580 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	581
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	582 \begin{methoddesc}{isAlive}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	583 Return whether the thread is alive.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	584
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	585 Roughly, a thread is alive from the moment the \method{start()} method
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	586 returns until its \method{run()} method terminates.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	587 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	588
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	589 \begin{methoddesc}{isDaemon}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	590 Return the thread's daemon flag.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	591 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	592
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	593 \begin{methoddesc}{setDaemon}{daemonic}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	594 Set the thread's daemon flag to the Boolean value \var{daemonic}.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	595 This must be called before \method{start()} is called.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	596
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	597 The initial value is inherited from the creating thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	598
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	599 The entire Python program exits when no active non-daemon
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	600 threads are left.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	601 \end{methoddesc}
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	602
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	603
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	604 \subsection{Timer Objects \label{timer-objects}}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	605
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	606 This class represents an action that should be run only after a certain amount
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	607 of time has passed --- a timer. \class{Timer} is a subclass of \class{Thread} and
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	608 as such also functions as an example of creating custom threads.
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	609
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	610 Timers are started, as with threads, by calling their \method{start()} method. The
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	611 timer can be stopped (before its action has begun) by calling the
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	612 \method{cancel()} method. The interval the timer will wait before executing
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	613 its action may not be exactly the same as the interval specified by the
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	614 user.
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	615
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	616 For example:
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	617 \begin{verbatim}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	618 def hello():
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	619 print "hello, world"
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	620
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	621 t = Timer(30.0, hello)
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	622 t.start() # after 30 seconds, "hello, world" will be printed
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	623 \end{verbatim}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	624
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	625 \begin{classdesc}{Timer}{interval, function, args=[], kwargs=\{\}}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	626 Create a timer that will run \var{function} with arguments \var{args} and
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	627 keyword arguments \var{kwargs}, after \var{interval} seconds have passed.
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	628 \end{classdesc}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	629
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	630 \begin{methoddesc}{cancel}{}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	631 Stop the timer, and cancel the execution of the timer's action. This will only
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	632 work if the timer is still in its waiting stage.
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	633 \end{methoddesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libthreading.tex @ 21467:4e35fa5d5708 legacy-trunk