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

annotate Doc/lib/libthreading.tex @ 39042:c02fa187e0f4 legacy-trunk

Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.

author	Neal Norwitz <nnorwitz@gmail.com>
date	Mon, 10 Jul 2006 00:23:17 +0000
parents	f7d23bca599f
children	0a6c5135d2de

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
32673 97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	52 \begin{classdesc*}{local}{}
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	53 A class that represents thread-local data. Thread-local data are data
32718 1bd3383bad98 Minor edits Andrew M. Kuchling <amk@amk.ca> parents: 32673 diff changeset	54 whose values are thread specific. To manage thread-local data, just
32673 97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	55 create an instance of \class{local} (or a subclass) and store
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	56 attributes on it:
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	57
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	58 \begin{verbatim}
32718 1bd3383bad98 Minor edits Andrew M. Kuchling <amk@amk.ca> parents: 32673 diff changeset	59 mydata = threading.local()
1bd3383bad98 Minor edits Andrew M. Kuchling <amk@amk.ca> parents: 32673 diff changeset	60 mydata.x = 1
32673 97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	61 \end{verbatim}
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	62
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	63 The instance's values will be different for separate threads.
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	64
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	65 For more details and extensive examples, see the documentation string
32718 1bd3383bad98 Minor edits Andrew M. Kuchling <amk@amk.ca> parents: 32673 diff changeset	66 of the \module{_threading_local} module.
32673 97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	67
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	68 \versionadded{2.4}
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	69 \end{classdesc*}
97768d87394a Implemented thread-local data as proposed on python-dev: Jim Fulton <jim@zope.com> parents: 29705 diff changeset	70
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	71 \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	72 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	73 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	74 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	75 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	76
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	77 \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	78 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	79 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	80 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	81 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	82 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	83 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	84
19400 be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	85 \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	86 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	87 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	88 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	89 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	90 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	91 1.
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	92 \end{funcdesc}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	93
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	94 \begin{funcdesc}{BoundedSemaphore}{\optional{value}}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	95 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	96 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	97 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	98 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	99 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	100 \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	101 \end{funcdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	102
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	103 \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	104 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	105 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	106 \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	107
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	108 \begin{classdesc*}{Timer}{}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	109 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	110 \end{classdesc*}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	111
29679 d0f15977f37f Add settrace() and setprofile() functions to the threading library. Jeremy Hylton <jeremy@alum.mit.edu> parents: 27114 diff changeset	112 \begin{funcdesc}{settrace}{func}
29689 f4e2e5a5ec62 Fix broken markup, & tweak a couple of things for consistency. Fred Drake <fdrake@acm.org> parents: 29679 diff changeset	113 Set a trace function\index{trace function} for all threads started
29679 d0f15977f37f Add settrace() and setprofile() functions to the threading library. Jeremy Hylton <jeremy@alum.mit.edu> parents: 27114 diff changeset	114 from the \module{threading} module. The \var{func} will be passed to
29689 f4e2e5a5ec62 Fix broken markup, & tweak a couple of things for consistency. Fred Drake <fdrake@acm.org> parents: 29679 diff changeset	115 \function{sys.settrace()} for each thread, before its \method{run()}
29679 d0f15977f37f Add settrace() and setprofile() functions to the threading library. Jeremy Hylton <jeremy@alum.mit.edu> parents: 27114 diff changeset	116 method is called.
29705 1536941b547f Add versionadded info for the 2 new threading module functions Neal Norwitz <nnorwitz@gmail.com> parents: 29689 diff changeset	117 \versionadded{2.3}
29679 d0f15977f37f Add settrace() and setprofile() functions to the threading library. Jeremy Hylton <jeremy@alum.mit.edu> parents: 27114 diff changeset	118 \end{funcdesc}
d0f15977f37f Add settrace() and setprofile() functions to the threading library. Jeremy Hylton <jeremy@alum.mit.edu> parents: 27114 diff changeset	119
d0f15977f37f Add settrace() and setprofile() functions to the threading library. Jeremy Hylton <jeremy@alum.mit.edu> parents: 27114 diff changeset	120 \begin{funcdesc}{setprofile}{func}
29689 f4e2e5a5ec62 Fix broken markup, & tweak a couple of things for consistency. Fred Drake <fdrake@acm.org> parents: 29679 diff changeset	121 Set a profile function\index{profile function} for all threads started
29679 d0f15977f37f Add settrace() and setprofile() functions to the threading library. Jeremy Hylton <jeremy@alum.mit.edu> parents: 27114 diff changeset	122 from the \module{threading} module. The \var{func} will be passed to
29689 f4e2e5a5ec62 Fix broken markup, & tweak a couple of things for consistency. Fred Drake <fdrake@acm.org> parents: 29679 diff changeset	123 \function{sys.setprofile()} for each thread, before its \method{run()}
29679 d0f15977f37f Add settrace() and setprofile() functions to the threading library. Jeremy Hylton <jeremy@alum.mit.edu> parents: 27114 diff changeset	124 method is called.
29705 1536941b547f Add versionadded info for the 2 new threading module functions Neal Norwitz <nnorwitz@gmail.com> parents: 29689 diff changeset	125 \versionadded{2.3}
29679 d0f15977f37f Add settrace() and setprofile() functions to the threading library. Jeremy Hylton <jeremy@alum.mit.edu> parents: 27114 diff changeset	126 \end{funcdesc}
d0f15977f37f Add settrace() and setprofile() functions to the threading library. Jeremy Hylton <jeremy@alum.mit.edu> parents: 27114 diff changeset	127
38794 f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	128 \begin{funcdesc}{stack_size}{\optional{size}}
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	129 Return the thread stack size used when creating new threads. The
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	130 optional \var{size} argument specifies the stack size to be used for
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	131 subsequently created threads, and must be 0 (use platform or
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	132 configured default) or a positive integer value of at least 32,768 (32kB).
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	133 If changing the thread stack size is unsupported, a \exception{ThreadError}
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	134 is raised. If the specified stack size is invalid, a \exception{ValueError}
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	135 is raised and the stack size is unmodified. 32kB is currently the minimum
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	136 supported stack size value to guarantee sufficient stack space for the
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	137 interpreter itself. Note that some platforms may have particular
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	138 restrictions on values for the stack size, such as requiring a minimum
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	139 stack size > 32kB or requiring allocation in multiples of the system
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	140 memory page size - platform documentation should be referred to for
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	141 more information (4kB pages are common; using multiples of 4096 for
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	142 the stack size is the suggested approach in the absence of more
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	143 specific information).
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	144 Availability: Windows, systems with \POSIX{} threads.
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	145 \versionadded{2.5}
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	146 \end{funcdesc}
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable. Andrew MacIntyre <andymac@bullseye.apana.org.au> parents: 38592 diff changeset	147
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	148 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	149
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	150 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	151 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	152 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	153 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	154 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	155 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	156 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	157 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	158
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	159 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	160
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	161
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	162 \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	163
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	164 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	165 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	166 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	167 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	168
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	169 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	170 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	171 \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	172 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	173 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	174 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	175 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	176 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	177 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	178 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	179 \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	180 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	181 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	182 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	183
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	184 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	185
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	186 \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	187 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	188
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	189 When invoked without arguments, block until the lock is
34997 21251e221e56 [Bug #1209880] Describe only the True/False return values from lock.acquire() Andrew M. Kuchling <amk@amk.ca> parents: 32718 diff changeset	190 unlocked, then set it to locked, 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	191
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	192 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	193 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	194
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	195 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	196 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	197 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	198 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	199 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	200
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	201 \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	202 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	203
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	204 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	205 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	206 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	207
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{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	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 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	217 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	218 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	219 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	220 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	221 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	222
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	223 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	224 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	225 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	226 \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	227 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	228 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	229 \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	230
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	231 \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	232 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	233
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	234 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	235 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	236 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	237 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	238 (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	239 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	240 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	241 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	242 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	243
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	244 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	245 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	246
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	247 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	248 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	249 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	250 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	251 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	252
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	253 \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	254 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	255 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	256 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	257 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	258 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	259 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	260
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	261 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	262 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	263
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	264 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	265 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	266
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	267
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	268 \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	269
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	270 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	271 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	272 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	273 same lock.)
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	274
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	275 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	276 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	277 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	278 \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	279 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	280
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	281 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	282 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	283 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	284 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	285 timeout.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	286
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	287 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	288 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	289 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	290
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	291 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	292 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	293 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	294 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	295 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	296
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	297 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	298 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	299 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	300 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	301 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	302 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	303 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	304 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	305
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	306 \begin{verbatim}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	307 # 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	308 cv.acquire()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	309 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	310 cv.wait()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	311 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	312 cv.release()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	313
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	314 # 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	315 cv.acquire()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	316 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	317 cv.notify()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	318 cv.release()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	319 \end{verbatim}
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 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	322 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	323 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	324 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	325 thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	326
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	327 \begin{classdesc}{Condition}{\optional{lock}}
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	328 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	329 \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	330 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	331 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	332 \end{classdesc}
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}{acquire}{*args}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	335 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	336 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	337 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	338 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	339
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	340 \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	341 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	342 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	343 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	344 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	345
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	346 \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	347 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	348 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	349 lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	350
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	351 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	352 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	353 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	354 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	355 and returns.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	356
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	357 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	358 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	359 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	360
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	361 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	362 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	363 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	364 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	365 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	366 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	367 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	368 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	369
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	370 \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	371 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	372 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	373 lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	374
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	375 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	376 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	377
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	378 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	379 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	380 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	381 thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	382
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	383 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	384 \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	385 \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	386 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	387
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	388 \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	389 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	390 \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	391 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	392
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	393
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	394 \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	395
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	396 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	397 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	398 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	399 \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	400
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	401 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	402 \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	403 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	404 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	405 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	406
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	407 \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	408 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	409 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	410 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	411
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	412 \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	413 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	414
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	415 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	416 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	417 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	418 \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	419 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	420 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	421 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	422 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	423 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	424
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	425 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	426 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	427
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	428 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	429 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	430 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	431 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	432 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	433
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	434 \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	435 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	436 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	437 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	438 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	439 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	440
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	441
19400 be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	442 \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	443
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	444 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	445 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	446 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	447 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	448
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	449 \begin{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	450 maxconnections = 5
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	451 ...
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	452 pool_sema = BoundedSemaphore(value=maxconnections)
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	453 \end{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	454
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	455 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	456 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	457
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	458 \begin{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	459 pool_sema.acquire()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	460 conn = connectdb()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	461 ... use connection ...
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	462 conn.close()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	463 pool_sema.release()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	464 \end{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	465
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	466 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	467 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	468 undetected.
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	469
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	470
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	471 \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	472
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	473 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	474 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	475
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	476 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	477 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	478 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	479
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	480
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	481 \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	482 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	483 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	484
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	485 \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	486 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	487 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	488
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	489 \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	490 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	491 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	492 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	493 at all.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	494 \end{methoddesc}
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 \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	497 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	498 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	499 \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	500 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	501
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	502 \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	503 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	504 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	505 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	506 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	507
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	508 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	509 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	510 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	511 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	512
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	513
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	514 \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	515
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	516 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	517 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	518 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	519 \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	520 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	521 \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	522 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	523
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	524 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	525 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	526 \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	527
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	528 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	529 '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	530 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	531 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	532 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	533 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	534 alive.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	535
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	536 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	537 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	538 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	539
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	540 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	541 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	542 \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	543
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	544 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	545 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	546 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	547 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	548 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	549
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	550 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	551 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	552 daemon thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	553
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	554 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	555 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	556 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	557 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	558 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	559 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	560 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	561 threads.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	562
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	563
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	564 \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	565 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	566 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	567 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	568
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	569 \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	570 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	571
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	572 \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	573 \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	574 called.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	575
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	576 \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	577 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	578 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	579
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	580 \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	581 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	582
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	583 \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	584 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	585
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	586 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	587 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	588 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	589 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	590
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	591 \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	592 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	593
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	594 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	595 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	596 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	597 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	598
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	599 \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	600 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	601
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	602 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	603 \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	604 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	605 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	606 \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	607 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	608
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	609 \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	610 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	611 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	612 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	613 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	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 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	616 should be a floating point number specifying a timeout for the
35248 8756973a6b99 backport [ 912943 ] 7.5.6 Thread Objects is too vague Georg Brandl <georg@python.org> parents: 34997 diff changeset	617 operation in seconds (or fractions thereof). As \method{join()} always
8756973a6b99 backport [ 912943 ] 7.5.6 Thread Objects is too vague Georg Brandl <georg@python.org> parents: 34997 diff changeset	618 returns \code{None}, you must call \method{isAlive()} to decide whether
8756973a6b99 backport [ 912943 ] 7.5.6 Thread Objects is too vague Georg Brandl <georg@python.org> parents: 34997 diff changeset	619 a timeout happened.
8756973a6b99 backport [ 912943 ] 7.5.6 Thread Objects is too vague Georg Brandl <georg@python.org> parents: 34997 diff changeset	620
8756973a6b99 backport [ 912943 ] 7.5.6 Thread Objects is too vague Georg Brandl <georg@python.org> parents: 34997 diff changeset	621 When the \var{timeout} argument is not present or \code{None}, the
8756973a6b99 backport [ 912943 ] 7.5.6 Thread Objects is too vague Georg Brandl <georg@python.org> parents: 34997 diff changeset	622 operation will block until the thread terminates.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	623
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	624 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	625
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	626 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	627 deadlock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	628
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	629 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	630 been started.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	631 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	632
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	633 \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	634 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	635 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	636
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	637 \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	638 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	639
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	640 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	641 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	642 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	643 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	644
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	645 \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	646 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	647
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	648 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	649 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	650 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	651
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	652 \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	653 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	654 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	655
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	656 \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	657 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	658 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	659
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	660 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	661
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	662 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	663 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	664 \end{methoddesc}
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	665
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	666
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	667 \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	668
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	669 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	670 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	671 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	672 creating custom threads.
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	673
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	674 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	675 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	676 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	677 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	678 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	679
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	680 For example:
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	681 \begin{verbatim}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	682 def hello():
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	683 print "hello, world"
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	684
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	685 t = Timer(30.0, hello)
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	686 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	687 \end{verbatim}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	688
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	689 \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	690 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	691 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	692 \end{classdesc}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	693
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	694 \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	695 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	696 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	697 \end{methoddesc}
37259 af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	698
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	699 \subsection{Using locks, conditions, and semaphores in the \keyword{with}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	700 statement \label{with-locks}}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	701
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	702 All of the objects provided by this module that have \method{acquire()} and
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	703 \method{release()} methods can be used as context managers for a \keyword{with}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	704 statement. The \method{acquire()} method will be called when the block is
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	705 entered, and \method{release()} will be called when the block is exited.
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	706
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	707 Currently, \class{Lock}, \class{RLock}, \class{Condition}, \class{Semaphore},
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	708 and \class{BoundedSemaphore} objects may be used as \keyword{with}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	709 statement context managers. For example:
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	710
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	711 \begin{verbatim}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	712 from __future__ import with_statement
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	713 import threading
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	714
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	715 some_rlock = threading.RLock()
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	716
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	717 with some_rlock:
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	718 print "some_rlock is locked while this executes"
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	719 \end{verbatim}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 35248 diff changeset	720

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libthreading.tex @ 39042:c02fa187e0f4 legacy-trunk