Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libthread.tex @ 8831:00a6bb65ff29 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Getting rid of this ancient stuff.
author Guido van Rossum <guido@python.org>
date Wed, 05 Aug 1998 21:10:09 +0000
parents 760dcf197048
children acfffe14628e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7877
8e5223680a9d Remove all uses of \sectcode; we can now use logical markup everywhere.
Fred Drake <fdrake@acm.org>
parents: 7817
diff changeset
1 \section{Built-in Module \module{thread}}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8617
diff changeset
2 \declaremodule{builtin}{thread}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8617
diff changeset
3
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8617
diff changeset
4 \modulesynopsis{Create multiple threads of control within one namespace.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8617
diff changeset
5
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 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
8 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
9 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
10 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
11 semaphores}) are provided.
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
12 \index{light-weight processes}
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
13 \index{processes, light-weight}
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
14 \index{binary semaphores}
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
15 \index{semaphores, binary}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16
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 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
18 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
19 (a.k.a. ``pthread'') implementation.
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
20 \index{pthreads}
7224
d33d45622e67 Oops, missed a \POSIX{} in an index entry.
Fred Drake <fdrake@acm.org>
parents: 7222
diff changeset
21 \indexii{threads}{\POSIX{}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 It defines the following constant and functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 Raised on thread-specific errors.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
8564
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
29 \begin{datadesc}{LockType}
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
30 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
31 \end{datadesc}
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
32
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
33 \begin{funcdesc}{start_new_thread}{function, args\optional{kwargs}}
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
34 Start a new thread. The thread executes the function \var{function}
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
35 with the argument list \var{args} (which must be a tuple). The
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
36 optional \var{kwargs} argument specifies a dictionary of keyword
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
37 arguments. When the
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1776
diff changeset
38 function returns, the thread silently exits. When the function
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 terminates with an unhandled exception, a stack trace is printed and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 then the thread exits (but other threads continue to run).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
43 \begin{funcdesc}{exit}{}
8564
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
44 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
45 will cause the thread to exit silently.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
48 \begin{funcdesc}{exit_thread}{}
8617
46b472ecb0f9 Added \deprecated to exit_thread() function.
Fred Drake <fdrake@acm.org>
parents: 8564
diff changeset
49 \deprecated{1.5.2}{Use \function{exit()}.}
8564
e87d22c7de3c Document optional kwargs argument to start_new_thread(). Also
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
50 This is an obsolete synonym for \function{exit()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
53 %\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
54 %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
55 %\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
56 %\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
57 %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
58 %\end{funcdesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
59
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 \begin{funcdesc}{allocate_lock}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 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
62 lock is initially unlocked.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64
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
65 \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
66 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
67 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
68 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
69 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
70 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
71 \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
72
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
73
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 Lock objects have the following methods:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
75
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
76 \begin{methoddesc}[lock]{acquire}{\optional{waitflag}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 Without the optional argument, this method acquires the lock
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 unconditionally, if necessary waiting until it is released by another
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 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
80 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
81 \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
82 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
83 immediately without waiting, while if it is nonzero, the lock is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 acquired unconditionally as before. If an argument is present, the
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
85 return value is \code{1} if the lock is acquired successfully,
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
86 \code{0} if not.
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
87 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
89 \begin{methoddesc}[lock]{release}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 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
91 necessarily by the same thread.
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
92 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
93
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
94 \begin{methoddesc}[lock]{locked}{}
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
95 Return the status of the lock:\ \code{1} if it has been acquired by
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
96 some thread, \code{0} if not.
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
97 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
98
7096
5bb884527446 Consistency: "{\bf ...}" ==> "\strong{...}"
Fred Drake <fdrake@acm.org>
parents: 6023
diff changeset
99 \strong{Caveats:}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
100
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 \begin{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
102 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
103 Threads interact strangely with interrupts: the
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
104 \exception{KeyboardInterrupt} exception will be received by an
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
105 arbitrary thread. (When the \module{signal}\refbimodindex{signal}
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
106 module is available, interrupts always go to the main thread.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
107
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
108 \item
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
109 Calling \function{sys.exit()} or raising the \exception{SystemExit}
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
110 exception is equivalent to calling \function{exit_thread()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
111
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
112 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
113 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
114 threads to run. (The most popular ones (\function{time.sleep()},
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
115 \method{\var{file}.read()}, \function{select.select()}) work as
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
116 expected.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
117
6023
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
118 \item
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
119 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
120 --- the \exception{KeyboardInterrupt} exception will happen after the
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
121 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
122
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
123 \item
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
124 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
125 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
126 they survive. On most other systems, they are killed without
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
127 executing \keyword{try} ... \keyword{finally} clauses or executing
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
128 object destructors.
7141
b81fb67d908d Added a bunch of "concept" index entries.
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
129 \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
130
6a25d8110b00 Updated platform specific notes (it is now more common to have this)
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
131 \item
7817
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
132 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
133 (except that \keyword{try} ... \keyword{finally} clauses are honored),
461738aaa533 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
134 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
135
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 \end{itemize}