Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libthread.tex @ 5792:dffabc620e4e legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Tweak re_tests and test_re to differentiate between groups that have no value and groups that are out of bounds.
author Guido van Rossum <guido@python.org>
date Tue, 15 Jul 1997 15:49:52 +0000
parents 9b7e6d9a528d
children 3468ea8645ca
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}}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
2 \bimodindex{thread}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 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
5 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
6 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
7 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
8 semaphores}) are provided.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9
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
10 The module is optional and supported on SGI IRIX 4.x and 5.x and Sun
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
11 Solaris 2.x systems, as well as on systems that have a PTHREAD
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1776
diff changeset
12 implementation (e.g.\ KSR).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 It defines the following constant and functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 \renewcommand{\indexsubitem}{(in module thread)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 Raised on thread-specific errors.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 \end{excdesc}
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 \begin{funcdesc}{start_new_thread}{func\, arg}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 Start a new thread. The thread executes the function \var{func}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 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
24 function returns, the thread silently exits. When the function
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 terminates with an unhandled exception, a stack trace is printed and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 then the thread exits (but other threads continue to run).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
29 \begin{funcdesc}{exit}{}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
30 This is a shorthand for \code{thread.exit_thread()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
33 \begin{funcdesc}{exit_thread}{}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
34 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
35 cause the thread to exit silently.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
38 %\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
39 %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
40 %\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
41 %\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
42 %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
43 %\end{funcdesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
44
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 \begin{funcdesc}{allocate_lock}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 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
47 lock is initially unlocked.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49
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
50 \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
51 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
52 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
53 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
54 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
55 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
56 \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
57
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 Lock objects have the following methods:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 \renewcommand{\indexsubitem}{(lock method)}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
61 \begin{funcdesc}{acquire}{\optional{waitflag}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 Without the optional argument, this method acquires the lock
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 unconditionally, if necessary waiting until it is released by another
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 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
65 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
66 \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
67 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
68 immediately without waiting, while if it is nonzero, the lock is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 acquired unconditionally as before. If an argument is present, the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 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
71 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 \begin{funcdesc}{release}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 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
75 necessarily by the same thread.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
76 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 \begin{funcdesc}{locked}{}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1776
diff changeset
79 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
80 thread, 0 if not.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
82
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 {\bf Caveats:}
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{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
86 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 Threads interact strangely with interrupts: the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 \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
89 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
90 always go to the main thread.)
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 \item
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
93 Calling \code{sys.exit()} or raising the \code{SystemExit} is
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
94 equivalent to calling \code{thread.exit_thread()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
95
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
96 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 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
98 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
99 \code{select}) work as expected.)
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 \end{itemize}