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

annotate Doc/lib/libthreading.tex @ 27998:e27f58a50737 legacy-trunk

SF bug #690377: Dud footnote reference in distutils docs

author	Raymond Hettinger <python@rcn.com>
date	Fri, 21 Feb 2003 02:47:09 +0000
parents	b2fc494963b2
children	d0f15977f37f

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
26897 3bc2af41c016 - fix use of \refmodule markup Fred Drake <fdrake@acm.org> parents: 26891 diff changeset	11 The \refmodule[dummythreading]{dummy_threading} module is provided for
3bc2af41c016 - fix use of \refmodule markup Fred Drake <fdrake@acm.org> parents: 26891 diff changeset	12 situations where \module{threading} cannot be used because
3bc2af41c016 - fix use of \refmodule markup Fred Drake <fdrake@acm.org> parents: 26891 diff changeset	13 \refmodule{thread} is missing.
26891 bc20e8b46de0 Add dummy_thread[ing] sections and reference these from libthread[ing]. Guido van Rossum <guido@python.org> parents: 22412 diff changeset	14
27114 b2fc494963b2 Strike any hint that from-import-* could ever be reasonable; it's a Fred Drake <fdrake@acm.org> parents: 26897 diff changeset	15 This module defines the following functions and objects:
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	16
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	17 \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	18 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	19 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	20 \function{enumerate()}.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	21 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	22 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	23
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	24 \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	25 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	26 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	27 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	28 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	29
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	30 \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	31 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	32 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	33 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	34 \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	35 is returned.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	36 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	37
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	38 \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	39 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	40 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	41 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	42 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	43 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	44
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	45 \begin{funcdesc}{Event}{}
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	46 A factory function that returns a new event object. An event manages
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	47 a flag that can be set to true with the \method{set()} method and
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	48 reset to false with the \method{clear()} method. The \method{wait()}
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	49 method blocks until the flag is true.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	50 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	51
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	52 \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	53 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	54 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	55 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	56 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	57
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	58 \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	59 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	60 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	61 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	62 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	63 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	64 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	65
19400 be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	66 \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	67 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	68 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	69 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	70 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	71 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	72 1.
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	73 \end{funcdesc}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	74
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	75 \begin{funcdesc}{BoundedSemaphore}{\optional{value}}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	76 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	77 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	78 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	79 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	80 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	81 \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	82 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	83
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	84 \begin{classdesc*}{Thread}{}
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	85 A class that represents a thread of control. This class can be safely
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	86 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	87 \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	88
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	89 \begin{classdesc*}{Timer}{}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	90 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	91 \end{classdesc*}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	92
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	93 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	94
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	95 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	96 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	97 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	98 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	99 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	100 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	101 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	102 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	103
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	104 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	105
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	106
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	107 \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	108
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	109 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	110 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	111 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	112 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	113
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	114 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	115 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	116 \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	117 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	118 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	119 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	120 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	121 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	122 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	123 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	124 \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	125 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	126 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	127 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	128
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	129 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	130
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	131 \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	132 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	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 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	135 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	136 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	137
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	138 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	139 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	140
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	141 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	142 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	143 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	144 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	145 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	146
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	147 \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	148 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	149
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	150 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	151 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	152 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	153
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	154 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	155
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	156 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	157 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	158
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	159
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	160 \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	161
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	162 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	163 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	164 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	165 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	166 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	167 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	168
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	169 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	170 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	171 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	172 \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	173 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	174 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	175 \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	176
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	177 \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	178 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	179
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	180 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	181 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	182 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	183 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	184 (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	185 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	186 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	187 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	188 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	189
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	190 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	191 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	192
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	193 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	194 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	195 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	196 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	197 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	198
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	199 \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	200 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	201 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	202 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	203 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	204 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	205 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	206
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	207 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	208 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	209
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	210 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	211 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	212
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	213
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	214 \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	215
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	216 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	217 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	218 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	219 same lock.)
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	220
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	221 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	222 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	223 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	224 \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	225 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	226
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	227 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	228 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	229 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	230 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	231 timeout.
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 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	234 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	235 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	236
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	237 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	238 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	239 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	240 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	241 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	242
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	243 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	244 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	245 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	246 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	247 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	248 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	249 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	250 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	251
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	252 \begin{verbatim}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	253 # 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	254 cv.acquire()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	255 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	256 cv.wait()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	257 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	258 cv.release()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	259
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	260 # 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	261 cv.acquire()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	262 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	263 cv.notify()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	264 cv.release()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	265 \end{verbatim}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	266
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	267 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	268 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	269 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	270 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	271 thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	272
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	273 \begin{classdesc}{Condition}{\optional{lock}}
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	274 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	275 \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	276 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	277 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	278 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	279
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	280 \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	281 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	282 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	283 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	284 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	285
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	286 \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	287 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	288 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	289 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	290 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	291
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	292 \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	293 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	294 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	295 lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	296
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	297 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	298 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	299 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	300 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	301 and returns.
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 \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	304 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	305 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	306
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	307 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	308 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	309 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	310 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	311 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	312 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	313 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	314 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	315
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	316 \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	317 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	318 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	319 lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	320
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	321 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	322 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	323
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	324 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	325 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	326 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	327 thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	328
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	329 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	330 \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	331 \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	332 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	333
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	334 \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	335 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	336 \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	337 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	338
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	339
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	340 \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	341
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	342 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	343 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	344 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	345 \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	346
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	347 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	348 \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	349 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	350 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	351 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	352
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	353 \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	354 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	355 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	356 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	357
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	358 \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	359 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	360
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	361 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	362 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	363 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	364 \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	365 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	366 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	367 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	368 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	369 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	370
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	371 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	372 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	373
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	374 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	375 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	376 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	377 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	378 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	379
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	380 \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	381 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	382 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	383 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	384 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	385 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	386
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	387
19400 be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	388 \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	389
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	390 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	391 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	392 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	393 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	394
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	395 \begin{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	396 maxconnections = 5
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	397 ...
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	398 pool_sema = BoundedSemaphore(value=maxconnections)
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	399 \end{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	400
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	401 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	402 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	403
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	404 \begin{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	405 pool_sema.acquire()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	406 conn = connectdb()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	407 ... use connection ...
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	408 conn.close()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	409 pool_sema.release()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	410 \end{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	411
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	412 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	413 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	414 undetected.
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	415
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	416
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	417 \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	418
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	419 This is one of the simplest mechanisms for communication between
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	420 threads: one thread signals an event and other threads wait for it.
8683 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 An event object manages an internal flag that can be set to true with
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	423 the \method{set()} method and reset to false with the \method{clear()}
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	424 method. The \method{wait()} method blocks until the flag is true.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	425
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{classdesc}{Event}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	428 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	429 \end{classdesc}
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}{isSet}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	432 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	433 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	434
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	435 \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	436 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	437 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	438 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	439 at all.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	440 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	441
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	442 \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	443 Reset the internal flag to false.
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	444 Subsequently, threads calling \method{wait()} will block until
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	445 \method{set()} is called to set the internal flag to true again.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	446 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	447
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	448 \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	449 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	450 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	451 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	452 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	453
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	454 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	455 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	456 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	457 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	458
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	459
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	460 \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	461
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	462 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	463 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	464 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	465 \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	466 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	467 \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	468 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	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 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	471 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	472 \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	473
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	474 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	475 '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	476 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	477 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	478 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	479 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	480 alive.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	481
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	482 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	483 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	484 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	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 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	487 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	488 \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	489
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	490 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	491 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	492 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	493 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	494 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	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 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	497 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	498 daemon thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	499
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	500 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	501 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	502 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	503 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	504 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	505 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	506 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	507 threads.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	508
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	509
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	510 \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	511 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	512 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	513 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	514
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	515 \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	516 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	517
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	518 \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	519 \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	520 called.
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{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	523 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	524 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	525
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	526 \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	527 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	528
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	529 \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	530 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	531
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	532 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	533 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	534 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	535 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	536
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	537 \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	538 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	539
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	540 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	541 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	542 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	543 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	544
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	545 \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	546 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	547
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	548 You may override this method in a subclass. The standard
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	549 \method{run()} method invokes the callable object passed to the
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	550 object's constructor as the \var{target} argument, if any, with
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	551 sequential and keyword arguments taken from the \var{args} and
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	552 \var{kwargs} arguments, respectively.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	553 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	554
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	555 \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	556 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	557 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	558 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	559 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	560
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	561 When the \var{timeout} argument is present and not \code{None}, it
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	562 should be a floating point number specifying a timeout for the
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	563 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	564
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	565 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	566
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	567 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	568 deadlock.
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 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	571 been started.
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}{getName}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	575 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	576 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	577
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	578 \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	579 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	580
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	581 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	582 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	583 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	584 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	585
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	586 \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	587 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	588
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	589 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	590 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	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}{isDaemon}{}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	594 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	595 \end{methoddesc}
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 \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	598 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	599 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	600
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	601 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	602
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	603 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	604 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	605 \end{methoddesc}
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	606
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	607
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	608 \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	609
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	610 This class represents an action that should be run only after a
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	611 certain amount of time has passed --- a timer. \class{Timer} is a
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	612 subclass of \class{Thread} and as such also functions as an example of
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	613 creating custom threads.
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	614
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	615 Timers are started, as with threads, by calling their \method{start()}
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	616 method. The timer can be stopped (before its action has begun) by
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	617 calling the \method{cancel()} method. The interval the timer will
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	618 wait before executing its action may not be exactly the same as the
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	619 interval specified by the user.
19727 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 For example:
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	622 \begin{verbatim}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	623 def hello():
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	624 print "hello, world"
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	625
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	626 t = Timer(30.0, hello)
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	627 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	628 \end{verbatim}
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{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	631 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	632 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	633 \end{classdesc}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	634
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	635 \begin{methoddesc}{cancel}{}
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	636 Stop the timer, and cancel the execution of the timer's action. This
36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	637 will only work if the timer is still in its waiting stage.
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	638 \end{methoddesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libthreading.tex @ 27998:e27f58a50737 legacy-trunk