Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libthread.tex @ 39496:352ffe77b71d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Patch #1535500: fix segfault in BZ2File.writelines and make sure it raises the correct exceptions.
author Georg Brandl <georg@python.org>
date Mon, 14 Aug 2006 21:42:55 +0000
parents f7d23bca599f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{thread} ---
10657
d203cb9ece37 Nits. Reference to signal module becomes a hyperlink.
Fred Drake <fdrake@acm.org>
parents: 9546
diff changeset
2 Multiple threads of control}
d203cb9ece37 Nits. Reference to signal module becomes a hyperlink.
Fred Drake <fdrake@acm.org>
parents: 9546
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8617
diff changeset
4 \declaremodule{builtin}{thread}
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
5 \modulesynopsis{Create multiple threads of control within one interpreter.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8617
diff changeset
6
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 This module provides low-level primitives for working with multiple
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1776
diff changeset
9 threads (a.k.a.\ \dfn{light-weight processes} or \dfn{tasks}) --- multiple
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 threads of control sharing their global data space. For
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1776
diff changeset
11 synchronization, simple locks (a.k.a.\ \dfn{mutexes} or \dfn{binary
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 semaphores}) are provided.
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
13 \index{light-weight processes}
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
14 \index{processes, light-weight}
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
15 \index{binary semaphores}
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
16 \index{semaphores, binary}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17
25881
8d44d614941d Clarify what versions of Windows are supported, and add Linux
Fred Drake <fdrake@acm.org>
parents: 22920
diff changeset
18 The module is optional. It is supported on Windows, Linux, SGI
7222
10fdf16f4de9 Consistently use \POSIX{} to denote POSIX. There were at least two different
Fred Drake <fdrake@acm.org>
parents: 7141
diff changeset
19 IRIX, Solaris 2.x, as well as on systems that have a \POSIX{} thread
26891
bc20e8b46de0 Add dummy_thread[ing] sections and reference these from libthread[ing].
Guido van Rossum <guido@python.org>
parents: 25881
diff changeset
20 (a.k.a. ``pthread'') implementation. For systems lacking the \module{thread}
26897
3bc2af41c016 - fix use of \refmodule markup
Fred Drake <fdrake@acm.org>
parents: 26891
diff changeset
21 module, the \refmodule[dummythread]{dummy_thread} module is available.
3bc2af41c016 - fix use of \refmodule markup
Fred Drake <fdrake@acm.org>
parents: 26891
diff changeset
22 It duplicates this module's interface and can be
3bc2af41c016 - fix use of \refmodule markup
Fred Drake <fdrake@acm.org>
parents: 26891
diff changeset
23 used as a drop-in replacement.
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
24 \index{pthreads}
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20468
diff changeset
25 \indexii{threads}{\POSIX}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 It defines the following constant and functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 Raised on thread-specific errors.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32
8564
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
33 \begin{datadesc}{LockType}
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
34 This is the type of lock objects.
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
35 \end{datadesc}
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
36
10657
d203cb9ece37 Nits. Reference to signal module becomes a hyperlink.
Fred Drake <fdrake@acm.org>
parents: 9546
diff changeset
37 \begin{funcdesc}{start_new_thread}{function, args\optional{, kwargs}}
20468
ebfd87e87884 Partial patch from SF #452266, by Jason Petrone.
Guido van Rossum <guido@python.org>
parents: 12243
diff changeset
38 Start a new thread and return its identifier. The thread executes the function
ebfd87e87884 Partial patch from SF #452266, by Jason Petrone.
Guido van Rossum <guido@python.org>
parents: 12243
diff changeset
39 \var{function} with the argument list \var{args} (which must be a tuple). The
ebfd87e87884 Partial patch from SF #452266, by Jason Petrone.
Guido van Rossum <guido@python.org>
parents: 12243
diff changeset
40 optional \var{kwargs} argument specifies a dictionary of keyword arguments.
ebfd87e87884 Partial patch from SF #452266, by Jason Petrone.
Guido van Rossum <guido@python.org>
parents: 12243
diff changeset
41 When the function returns, the thread silently exits. When the function
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42 terminates with an unhandled exception, a stack trace is printed and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 then the thread exits (but other threads continue to run).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45
29784
4fc56cae4eb8 Document interrupt_main()
Kurt B. Kaiser <kbk@shore.net>
parents: 26897
diff changeset
46 \begin{funcdesc}{interrupt_main}{}
38170
8b6017c937ac Add \exception markup
George Yoshida <dynkin@gmail.com>
parents: 37259
diff changeset
47 Raise a \exception{KeyboardInterrupt} exception in the main thread. A subthread
8b6017c937ac Add \exception markup
George Yoshida <dynkin@gmail.com>
parents: 37259
diff changeset
48 can use this function to interrupt the main thread.
29793
e6a78dd425c8 Add versionadded. Remove duplicate "to"
Neal Norwitz <nnorwitz@gmail.com>
parents: 29784
diff changeset
49 \versionadded{2.3}
29784
4fc56cae4eb8 Document interrupt_main()
Kurt B. Kaiser <kbk@shore.net>
parents: 26897
diff changeset
50 \end{funcdesc}
4fc56cae4eb8 Document interrupt_main()
Kurt B. Kaiser <kbk@shore.net>
parents: 26897
diff changeset
51
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
52 \begin{funcdesc}{exit}{}
8564
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
53 Raise the \exception{SystemExit} exception. When not caught, this
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
54 will cause the thread to exit silently.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
57 %\begin{funcdesc}{exit_prog}{status}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
58 %Exit all threads and report the value of the integer argument
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
59 %\var{status} as the exit status of the entire program.
10657
d203cb9ece37 Nits. Reference to signal module becomes a hyperlink.
Fred Drake <fdrake@acm.org>
parents: 9546
diff changeset
60 %\strong{Caveat:} code in pending \keyword{finally} clauses, in this thread
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
61 %or in other threads, is not executed.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
62 %\end{funcdesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
63
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \begin{funcdesc}{allocate_lock}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 Return a new lock object. Methods of locks are described below. The
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 lock is initially unlocked.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
68
1776
5257af80e161 * Doc/libfuncs.tex: don't use $math$ in description of pow(x,y,z);
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
69 \begin{funcdesc}{get_ident}{}
5257af80e161 * Doc/libfuncs.tex: don't use $math$ in description of pow(x,y,z);
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
70 Return the `thread identifier' of the current thread. This is a
5257af80e161 * Doc/libfuncs.tex: don't use $math$ in description of pow(x,y,z);
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
71 nonzero integer. Its value has no direct meaning; it is intended as a
5257af80e161 * Doc/libfuncs.tex: don't use $math$ in description of pow(x,y,z);
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
72 magic cookie to be used e.g. to index a dictionary of thread-specific
5257af80e161 * Doc/libfuncs.tex: don't use $math$ in description of pow(x,y,z);
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
73 data. Thread identifiers may be recycled when a thread exits and
5257af80e161 * Doc/libfuncs.tex: don't use $math$ in description of pow(x,y,z);
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
74 another thread is created.
5257af80e161 * Doc/libfuncs.tex: don't use $math$ in description of pow(x,y,z);
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
75 \end{funcdesc}
5257af80e161 * Doc/libfuncs.tex: don't use $math$ in description of pow(x,y,z);
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
76
38794
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
77 \begin{funcdesc}{stack_size}{\optional{size}}
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
78 Return the thread stack size used when creating new threads. The
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
79 optional \var{size} argument specifies the stack size to be used for
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
80 subsequently created threads, and must be 0 (use platform or
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
81 configured default) or a positive integer value of at least 32,768 (32kB).
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
82 If changing the thread stack size is unsupported, a \exception{ThreadError}
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
83 is raised. If the specified stack size is invalid, a \exception{ValueError}
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
84 is raised and the stack size is unmodified. 32kB is currently the minimum
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
85 supported stack size value to guarantee sufficient stack space for the
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
86 interpreter itself. Note that some platforms may have particular
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
87 restrictions on values for the stack size, such as requiring a minimum
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
88 stack size > 32kB or requiring allocation in multiples of the system
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
89 memory page size - platform documentation should be referred to for
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
90 more information (4kB pages are common; using multiples of 4096 for
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
91 the stack size is the suggested approach in the absence of more
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
92 specific information).
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
93 Availability: Windows, systems with \POSIX{} threads.
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
94 \versionadded{2.5}
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
95 \end{funcdesc}
f7d23bca599f Patch #1454481: Make thread stack size runtime tunable.
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 38592
diff changeset
96
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
97
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
98 Lock objects have the following methods:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
99
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
100 \begin{methoddesc}[lock]{acquire}{\optional{waitflag}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 Without the optional argument, this method acquires the lock
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
102 unconditionally, if necessary waiting until it is released by another
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
103 thread (only one thread at a time can acquire a lock --- that's their
34997
21251e221e56 [Bug #1209880] Describe only the True/False return values from lock.acquire()
Andrew M. Kuchling <amk@amk.ca>
parents: 29793
diff changeset
104 reason for existence). If the integer
9546
aa961a46ae9e Minor markup nit to ease conversion processing.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
105 \var{waitflag} argument is present, the action depends on its
aa961a46ae9e Minor markup nit to ease conversion processing.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
106 value: if it is zero, the lock is only acquired if it can be acquired
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
107 immediately without waiting, while if it is nonzero, the lock is
34997
21251e221e56 [Bug #1209880] Describe only the True/False return values from lock.acquire()
Andrew M. Kuchling <amk@amk.ca>
parents: 29793
diff changeset
108 acquired unconditionally as before. The
22920
2392af05f052 Update docs for bool changes by Guido around April 6
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
109 return value is \code{True} if the lock is acquired successfully,
2392af05f052 Update docs for bool changes by Guido around April 6
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
110 \code{False} if not.
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
111 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
112
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
113 \begin{methoddesc}[lock]{release}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
114 Releases the lock. The lock must have been acquired earlier, but not
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 necessarily by the same thread.
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
116 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
117
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
118 \begin{methoddesc}[lock]{locked}{}
22920
2392af05f052 Update docs for bool changes by Guido around April 6
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
119 Return the status of the lock:\ \code{True} if it has been acquired by
2392af05f052 Update docs for bool changes by Guido around April 6
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
120 some thread, \code{False} if not.
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
121 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
122
37259
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
123 In addition to these methods, lock objects can also be used via the
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
124 \keyword{with} statement, e.g.:
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
125
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
126 \begin{verbatim}
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
127 from __future__ import with_statement
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
128 import thread
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
129
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
130 a_lock = thread.allocate_lock()
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
131
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
132 with a_lock:
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
133 print "a_lock is locked while this executes"
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
134 \end{verbatim}
af24eb3bbfce Document objects that can be used with the ``with`` statement.
Phillip J. Eby <pje@telecommunity.com>
parents: 34997
diff changeset
135
7096
5bb884527446 Consistency: "{\bf ...}" ==> "\strong{...}"
Fred Drake <fdrake@acm.org>
parents: 6023
diff changeset
136 \strong{Caveats:}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
137
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
138 \begin{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
139 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
140 Threads interact strangely with interrupts: the
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
141 \exception{KeyboardInterrupt} exception will be received by an
10657
d203cb9ece37 Nits. Reference to signal module becomes a hyperlink.
Fred Drake <fdrake@acm.org>
parents: 9546
diff changeset
142 arbitrary thread. (When the \refmodule{signal}\refbimodindex{signal}
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
143 module is available, interrupts always go to the main thread.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
144
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
145 \item
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
146 Calling \function{sys.exit()} or raising the \exception{SystemExit}
12243
be3e0d197522 Noted by Guido:
Fred Drake <fdrake@acm.org>
parents: 10657
diff changeset
147 exception is equivalent to calling \function{exit()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
148
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
149 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
150 Not all built-in functions that may block waiting for I/O allow other
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
151 threads to run. (The most popular ones (\function{time.sleep()},
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
152 \method{\var{file}.read()}, \function{select.select()}) work as
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
153 expected.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
154
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
155 \item
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
156 It is not possible to interrupt the \method{acquire()} method on a lock
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
157 --- the \exception{KeyboardInterrupt} exception will happen after the
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
158 lock has been acquired.
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
159
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
160 \item
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
161 When the main thread exits, it is system defined whether the other
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
162 threads survive. On SGI IRIX using the native thread implementation,
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
163 they survive. On most other systems, they are killed without
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
164 executing \keyword{try} ... \keyword{finally} clauses or executing
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
165 object destructors.
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
166 \indexii{threads}{IRIX}
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
167
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
168 \item
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
169 When the main thread exits, it does not do any of its usual cleanup
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
170 (except that \keyword{try} ... \keyword{finally} clauses are honored),
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
171 and the standard I/O files are not flushed.
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
172
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 \end{itemize}