Mercurial > cpython-lru_cache-weakref

annotate Doc/libthread.tex @ 6719:faebc1940432 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Understand -Xlinker option.
author Guido van Rossum <guido@python.org>
date Tue, 02 Dec 1997 20:38:11 +0000
parents 6a25d8110b00
children 5bb884527446
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.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
11 The module is optional. It is supported on Windows NT and '95, SGI
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
12 IRIX, Solaris 2.x, as well as on systems that have a POSIX thread
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
13 (a.k.a. ``pthread'') implementation.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 It defines the following constant and functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \renewcommand{\indexsubitem}{(in module thread)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 Raised on thread-specific errors.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 \begin{funcdesc}{start_new_thread}{func\, arg}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 Start a new thread. The thread executes the function \var{func}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 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
25 function returns, the thread silently exits. When the function
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 terminates with an unhandled exception, a stack trace is printed and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 then the thread exits (but other threads continue to run).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
30 \begin{funcdesc}{exit}{}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
31 This is a shorthand for \code{thread.exit_thread()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
34 \begin{funcdesc}{exit_thread}{}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
35 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
36 cause the thread to exit silently.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
39 %\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
40 %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
41 %\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
42 %\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
43 %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
44 %\end{funcdesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
45
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \begin{funcdesc}{allocate_lock}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 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
48 lock is initially unlocked.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50
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
51 \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
52 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
53 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
54 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
55 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
56 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
57 \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
58
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 Lock objects have the following methods:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 \renewcommand{\indexsubitem}{(lock method)}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
62 \begin{funcdesc}{acquire}{\optional{waitflag}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 Without the optional argument, this method acquires the lock
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 unconditionally, if necessary waiting until it is released by another
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 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
66 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
67 \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
68 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
69 immediately without waiting, while if it is nonzero, the lock is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 acquired unconditionally as before. If an argument is present, the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 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
72 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 \begin{funcdesc}{release}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 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
76 necessarily by the same thread.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 \begin{funcdesc}{locked}{}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1776
diff changeset
80 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
81 thread, 0 if not.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
83
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 {\bf Caveats:}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
85
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
86 \begin{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 Threads interact strangely with interrupts: the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
89 \code{KeyboardInterrupt} exception will be received by an arbitrary
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
90 thread. (When the \code{signal} module is available, interrupts
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
91 always go to the main thread.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
92
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 \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
94 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
95 equivalent to calling \code{thread.exit_thread()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
96
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
98 Not all built-in functions that may block waiting for I/O allow other
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
99 threads to run. (The most popular ones (\code{sleep}, \code{read},
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
100 \code{select}) work as expected.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
101
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
102 \item
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
103 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
104 -- 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
105 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
106
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
107 \item
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
108 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
109 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
110 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
111 executing ``try-finally'' clauses or executing object destructors.
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 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
115 (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
116 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
117
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
118 \end{itemize}