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

annotate Doc/lib/libthreading.tex @ 33845:032f342efcd2 legacy-trunk

Very few little improvements.

author	Facundo Batista <facundobatista@gmail.com>
date	Tue, 26 Oct 2004 23:38:46 +0000
parents	1bd3383bad98
children	21251e221e56

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
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	128 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	129
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	130 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	131 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	132 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	133 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	134 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	135 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	136 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	137 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	138
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	139 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	140
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	141
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	142 \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	143
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	144 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	145 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	146 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	147 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	148
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	149 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	150 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	151 \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	152 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	153 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	154 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	155 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	156 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	157 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	158 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	159 \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	160 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	161 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	162 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	163
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	164 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	165
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	166 \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	167 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	168
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	169 When invoked without arguments, block until the lock is
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	170 unlocked, then set it to locked, and return. There is no
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	171 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	172
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	173 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	174 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	175
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	176 When invoked 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	177 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	178 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	179 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	180 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	181
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	182 \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	183 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	184
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	185 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	186 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	187 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	188
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	189 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	190
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	191 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	192 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	193
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	194
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	195 \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	196
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	197 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	198 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	199 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	200 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	201 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	202 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	203
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	204 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	205 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	206 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	207 \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	208 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	209 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	210 \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	211
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	212 \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	213 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	214
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	215 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	216 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	217 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	218 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	219 (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	220 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	221 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	222 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	223 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	224
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	225 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	226 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	227
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	228 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	229 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	230 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	231 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	232 \end{methoddesc}
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 \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	235 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	236 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	237 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	238 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	239 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	240 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	241
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	242 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	243 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	244
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	245 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	246 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	247
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	248
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	249 \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	250
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	251 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	252 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	253 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	254 same lock.)
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	255
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	256 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	257 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	258 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	259 \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	260 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	261
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	262 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	263 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	264 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	265 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	266 timeout.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	267
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	268 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	269 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	270 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	271
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	272 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	273 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	274 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	275 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	276 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	277
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	278 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	279 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	280 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	281 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	282 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	283 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	284 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	285 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	286
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	287 \begin{verbatim}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	288 # 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	289 cv.acquire()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	290 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	291 cv.wait()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	292 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	293 cv.release()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	294
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	295 # 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	296 cv.acquire()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	297 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	298 cv.notify()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	299 cv.release()
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	300 \end{verbatim}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	301
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	302 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	303 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	304 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	305 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	306 thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	307
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	308 \begin{classdesc}{Condition}{\optional{lock}}
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	309 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	310 \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	311 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	312 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	313 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	314
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	315 \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	316 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	317 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	318 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	319 \end{methoddesc}
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 \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	322 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	323 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	324 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	325 \end{methoddesc}
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{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	328 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	329 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	330 lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	331
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	332 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	333 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	334 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	335 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	336 and returns.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	337
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	338 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	339 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	340 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	341
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	342 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	343 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	344 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	345 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	346 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	347 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	348 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	349 \end{methoddesc}
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 \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	352 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	353 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	354 lock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	355
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	356 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	357 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	358
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	359 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	360 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	361 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	362 thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	363
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	364 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	365 \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	366 \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	367 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	368
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	369 \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	370 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	371 \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	372 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	373
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	374
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	375 \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	376
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	377 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	378 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	379 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	380 \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	381
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	382 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	383 \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	384 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	385 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	386 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	387
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	388 \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	389 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	390 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	391 \end{classdesc}
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 \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	394 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	395
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	396 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	397 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	398 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	399 \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	400 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	401 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	402 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	403 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	404 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	405
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	406 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	407 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	408
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	409 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	410 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	411 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	412 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	413 \end{methoddesc}
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 \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	416 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	417 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	418 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	419 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	420 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	421
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	422
19400 be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	423 \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	424
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	425 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	426 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	427 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	428 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	429
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	430 \begin{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	431 maxconnections = 5
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	432 ...
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	433 pool_sema = BoundedSemaphore(value=maxconnections)
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	434 \end{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	435
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	436 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	437 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	438
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	439 \begin{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	440 pool_sema.acquire()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	441 conn = connectdb()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	442 ... use connection ...
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	443 conn.close()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	444 pool_sema.release()
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	445 \end{verbatim}
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	446
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	447 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	448 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	449 undetected.
be5be989caff Added documentation for BoundedSemaphore(), contributed by Skip Montanaro. Fred Drake <fdrake@acm.org> parents: 18416 diff changeset	450
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	451
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	452 \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	453
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	454 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	455 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	456
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	457 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	458 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	459 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	460
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	461
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	462 \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	463 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	464 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	465
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	466 \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	467 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	468 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	469
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	470 \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	471 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	472 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	473 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	474 at all.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	475 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	476
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	477 \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	478 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	479 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	480 \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	481 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	482
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	483 \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	484 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	485 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	486 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	487 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	488
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	489 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	490 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	491 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	492 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	493
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	494
f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	495 \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	496
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	497 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	498 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	499 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	500 \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	501 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	502 \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	503 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	504
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	505 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	506 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	507 \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	508
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	509 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	510 '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	511 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	512 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	513 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	514 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	515 alive.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	516
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	517 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	518 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	519 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	520
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	521 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	522 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	523 \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	524
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	525 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	526 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	527 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	528 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	529 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	530
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	531 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	532 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	533 daemon thread.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	534
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	535 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	536 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	537 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	538 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	539 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	540 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	541 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	542 threads.
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
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	545 \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	546 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	547 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	548 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	549
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	550 \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	551 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	552
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	553 \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	554 \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	555 called.
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	556
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	557 \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	558 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	559 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	560
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	561 \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	562 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	563
18009 50e3380b086a Some general cleanup of the threading module documentation, including Fred Drake <fdrake@acm.org> parents: 10730 diff changeset	564 \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	565 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	566
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	567 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	568 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	569 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	570 \end{classdesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	571
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	572 \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	573 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	574
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	575 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	576 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	577 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	578 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	579
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	580 \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	581 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	582
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	583 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	584 \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	585 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	586 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	587 \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	588 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	589
10392 f54bac5af98c Fixed tons of small markup problems. Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	590 \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	591 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	592 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	593 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	594 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	595
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	596 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	597 should be a floating point number specifying a timeout for the
8683 a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	598 operation in seconds (or fractions thereof).
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	599
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	600 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	601
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	602 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	603 deadlock.
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	604
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	605 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	606 been started.
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
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	609 \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	610 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	611 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	612
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	613 \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	614 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	615
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	616 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	617 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	618 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	619 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	620
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	621 \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	622 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	623
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	624 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	625 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	626 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	627
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	628 \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	629 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	630 \end{methoddesc}
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	631
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	632 \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	633 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	634 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	635
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	636 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	637
a0324a3068e9 Added libthreading.tex ; this is mostly the contents of threading_api.py, Andrew M. Kuchling <amk@amk.ca> parents: diff changeset	638 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	639 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	640 \end{methoddesc}
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	641
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	642
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	643 \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	644
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	645 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	646 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	647 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	648 creating custom threads.
19727 f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	649
22412 36c52cfbd0b7 Adjust some poor wording in the text that explains what events are used Fred Drake <fdrake@acm.org> parents: 19727 diff changeset	650 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	651 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	652 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	653 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	654 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	655
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	656 For example:
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	657 \begin{verbatim}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	658 def hello():
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	659 print "hello, world"
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	660
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	661 t = Timer(30.0, hello)
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	662 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	663 \end{verbatim}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	664
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	665 \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	666 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	667 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	668 \end{classdesc}
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	669
f3036d4e3c22 Patch #428326: New class threading.Timer. Martin v. Löwis <martin@v.loewis.de> parents: 19400 diff changeset	670 \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	671 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	672 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	673 \end{methoddesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libthreading.tex @ 33845:032f342efcd2 legacy-trunk