Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libthread.tex @ 7278:59d2761ba1cf legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Remove obsolete pagenumbering / pagestyle cruft.
author Fred Drake <fdrake@acm.org>
date Fri, 13 Feb 1998 07:08:56 +0000
parents bf4e790bd61a
children 0cbc9df882b6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Built-in Module \sectcode{thread}}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
2 \label{module-thread}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \bimodindex{thread}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 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
6 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
7 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
8 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
9 semaphores}) are provided.
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
10 \index{light-weight processes}
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
11 \index{processes, light-weight}
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
12 \index{binary semaphores}
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
13 \index{semaphores, binary}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
15 The module is optional. It is supported on Windows NT and '95, SGI
7222
10fdf16f4de9 Consistently use \POSIX{} to denote POSIX. There were at least two different
Fred Drake <fdrake@acm.org>
parents: 7141
diff changeset
16 IRIX, Solaris 2.x, as well as on systems that have a \POSIX{} thread
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
17 (a.k.a. ``pthread'') implementation.
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
18 \index{pthreads}
7224
d33d45622e67 Oops, missed a \POSIX{} in an index entry.
Fred Drake <fdrake@acm.org>
parents: 7222
diff changeset
19 \indexii{threads}{\POSIX{}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 It defines the following constant and functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7224
diff changeset
23 \setindexsubitem{(in module thread)}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 Raised on thread-specific errors.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 \begin{funcdesc}{start_new_thread}{func\, arg}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 Start a new thread. The thread executes the function \var{func}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 with the argument list \var{arg} (which must be a tuple). When the
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1776
diff changeset
31 function returns, the thread silently exits. When the function
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 terminates with an unhandled exception, a stack trace is printed and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 then the thread exits (but other threads continue to run).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
36 \begin{funcdesc}{exit}{}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
37 This is a shorthand for \code{thread.exit_thread()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
40 \begin{funcdesc}{exit_thread}{}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
41 Raise the \code{SystemExit} exception. When not caught, this will
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
42 cause the thread to exit silently.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
45 %\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
46 %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
47 %\var{status} as the exit status of the entire program.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
48 %\strong{Caveat:} code in pending \code{finally} clauses, in this thread
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
49 %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
50 %\end{funcdesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
51
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \begin{funcdesc}{allocate_lock}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 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
54 lock is initially unlocked.
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
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
57 \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
58 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
59 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
60 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
61 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
62 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
63 \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
64
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 Lock objects have the following methods:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7224
diff changeset
67 \setindexsubitem{(lock method)}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
68 \begin{funcdesc}{acquire}{\optional{waitflag}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 Without the optional argument, this method acquires the lock
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 unconditionally, if necessary waiting until it is released by another
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 thread (only one thread at a time can acquire a lock --- that's their
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 reason for existence), and returns \code{None}. If the integer
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1776
diff changeset
73 \var{waitflag} argument is present, the action depends on its value:\
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 if it is zero, the lock is only acquired if it can be acquired
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 immediately without waiting, while if it is nonzero, the lock is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
76 acquired unconditionally as before. If an argument is present, the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 return value is 1 if the lock is acquired successfully, 0 if not.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
79
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 \begin{funcdesc}{release}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 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
82 necessarily by the same thread.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
84
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
85 \begin{funcdesc}{locked}{}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1776
diff changeset
86 Return the status of the lock:\ 1 if it has been acquired by some
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 thread, 0 if not.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
89
7096
5bb884527446 Consistency: "{\bf ...}" ==> "\strong{...}"
Fred Drake <fdrake@acm.org>
parents: 6023
diff changeset
90 \strong{Caveats:}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
91
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 \begin{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 Threads interact strangely with interrupts: the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
95 \code{KeyboardInterrupt} exception will be received by an arbitrary
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
96 thread. (When the \code{signal}\refbimodindex{signal} module is
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
97 available, interrupts always go to the main thread.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
98
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
99 \item
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
100 Calling \code{sys.exit()} or raising the \code{SystemExit} exception is
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
101 equivalent to calling \code{thread.exit_thread()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
102
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
103 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
104 Not all built-in functions that may block waiting for I/O allow other
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
105 threads to run. (The most popular ones (\code{sleep()}, \code{read()},
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
106 \code{select()}) work as expected.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
107
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
108 \item
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
109 It is not possible to interrupt the \code{acquire()} method on a lock
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
110 -- the \code{KeyboardInterrupt} exception will happen after the lock
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
111 has been acquired.
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
112
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
113 \item
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
114 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
115 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
116 they survive. On most other systems, they are killed without
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
117 executing ``try-finally'' clauses or executing object destructors.
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
118 \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
119
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
120 \item
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
121 When the main thread exits, it doesn't do any of its usual cleanup
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
122 (except that ``try-finally'' clauses are honored), and the standard
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
123 I/O files are not flushed.
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
124
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 \end{itemize}