Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="module-threading.html" /> | |
13 | <link rel="prev" href="module-select.html" /> | |
14 | <link rel="parent" href="someos.html" /> | |
15 | <link rel="next" href="module-threading.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>7.4 thread -- Multiple threads of control</title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="7.3.1 Polling Objects" | |
25 | href="poll-objects.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="7. Optional Operating System" | |
28 | href="someos.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="7.5 threading " | |
31 | href="module-threading.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="poll-objects.html">7.3.1 Polling Objects</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="module-threading.html">7.5 threading </A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H1><A NAME="SECTION009400000000000000000"> | |
56 | 7.4 <tt class="module">thread</tt> -- | |
57 | Multiple threads of control</A> | |
58 | </H1> | |
59 | ||
60 | <P> | |
61 | <A NAME="module-thread"></A> | |
62 | ||
63 | <P> | |
64 | This module provides low-level primitives for working with multiple | |
65 | threads (a.k.a. <i class="dfn">light-weight processes</i> or <i class="dfn">tasks</i>) -- multiple | |
66 | threads of control sharing their global data space. For | |
67 | synchronization, simple locks (a.k.a. <i class="dfn">mutexes</i> or <i class="dfn">binary | |
68 | semaphores</i>) are provided. | |
69 | <a id='l2h-2700' xml:id='l2h-2700'></a> | |
70 | ||
71 | <P> | |
72 | The module is optional. It is supported on Windows, Linux, SGI | |
73 | IRIX, Solaris 2.x, as well as on systems that have a POSIX thread | |
74 | (a.k.a. ``pthread'') implementation. For systems lacking the <tt class="module">thread</tt> | |
75 | module, the <tt class="module"><a href="module-dummythread.html">dummy_thread</a></tt> module is available. | |
76 | It duplicates this module's interface and can be | |
77 | used as a drop-in replacement. | |
78 | <a id='l2h-2701' xml:id='l2h-2701'></a> | |
79 | <a id='l2h-2688' xml:id='l2h-2688'></a> | |
80 | <P> | |
81 | It defines the following constant and functions: | |
82 | ||
83 | <P> | |
84 | <dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-2689' xml:id='l2h-2689' class="exception">error</tt></b></dt> | |
85 | <dd> | |
86 | Raised on thread-specific errors. | |
87 | </dd></dl> | |
88 | ||
89 | <P> | |
90 | <dl><dt><b><tt id='l2h-2690' xml:id='l2h-2690'>LockType</tt></b></dt> | |
91 | <dd> | |
92 | This is the type of lock objects. | |
93 | </dd></dl> | |
94 | ||
95 | <P> | |
96 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
97 | <td><nobr><b><tt id='l2h-2691' xml:id='l2h-2691' class="function">start_new_thread</tt></b>(</nobr></td> | |
98 | <td><var>function, args</var><big>[</big><var>, kwargs</var><big>]</big><var></var>)</td></tr></table></dt> | |
99 | <dd> | |
100 | Start a new thread and return its identifier. The thread executes the function | |
101 | <var>function</var> with the argument list <var>args</var> (which must be a tuple). The | |
102 | optional <var>kwargs</var> argument specifies a dictionary of keyword arguments. | |
103 | When the function returns, the thread silently exits. When the function | |
104 | terminates with an unhandled exception, a stack trace is printed and | |
105 | then the thread exits (but other threads continue to run). | |
106 | </dl> | |
107 | ||
108 | <P> | |
109 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
110 | <td><nobr><b><tt id='l2h-2692' xml:id='l2h-2692' class="function">interrupt_main</tt></b>(</nobr></td> | |
111 | <td><var></var>)</td></tr></table></dt> | |
112 | <dd> | |
113 | Raise a KeyboardInterrupt in the main thread. A subthread can use this | |
114 | function to interrupt the main thread. | |
115 | ||
116 | <span class="versionnote">New in version 2.3.</span> | |
117 | ||
118 | </dl> | |
119 | ||
120 | <P> | |
121 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
122 | <td><nobr><b><tt id='l2h-2693' xml:id='l2h-2693' class="function">exit</tt></b>(</nobr></td> | |
123 | <td><var></var>)</td></tr></table></dt> | |
124 | <dd> | |
125 | Raise the <tt class="exception">SystemExit</tt> exception. When not caught, this | |
126 | will cause the thread to exit silently. | |
127 | </dl> | |
128 | ||
129 | <P> | |
130 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
131 | <td><nobr><b><tt id='l2h-2694' xml:id='l2h-2694' class="function">allocate_lock</tt></b>(</nobr></td> | |
132 | <td><var></var>)</td></tr></table></dt> | |
133 | <dd> | |
134 | Return a new lock object. Methods of locks are described below. The | |
135 | lock is initially unlocked. | |
136 | </dl> | |
137 | ||
138 | <P> | |
139 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
140 | <td><nobr><b><tt id='l2h-2695' xml:id='l2h-2695' class="function">get_ident</tt></b>(</nobr></td> | |
141 | <td><var></var>)</td></tr></table></dt> | |
142 | <dd> | |
143 | Return the `thread identifier' of the current thread. This is a | |
144 | nonzero integer. Its value has no direct meaning; it is intended as a | |
145 | magic cookie to be used e.g. to index a dictionary of thread-specific | |
146 | data. Thread identifiers may be recycled when a thread exits and | |
147 | another thread is created. | |
148 | </dl> | |
149 | ||
150 | <P> | |
151 | Lock objects have the following methods: | |
152 | ||
153 | <P> | |
154 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
155 | <td><nobr><b><tt id='l2h-2696' xml:id='l2h-2696' class="method">acquire</tt></b>(</nobr></td> | |
156 | <td><var></var><big>[</big><var>waitflag</var><big>]</big><var></var>)</td></tr></table></dt> | |
157 | <dd> | |
158 | Without the optional argument, this method acquires the lock | |
159 | unconditionally, if necessary waiting until it is released by another | |
160 | thread (only one thread at a time can acquire a lock -- that's their | |
161 | reason for existence). If the integer | |
162 | <var>waitflag</var> argument is present, the action depends on its | |
163 | value: if it is zero, the lock is only acquired if it can be acquired | |
164 | immediately without waiting, while if it is nonzero, the lock is | |
165 | acquired unconditionally as before. The | |
166 | return value is <code>True</code> if the lock is acquired successfully, | |
167 | <code>False</code> if not. | |
168 | </dl> | |
169 | ||
170 | <P> | |
171 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
172 | <td><nobr><b><tt id='l2h-2697' xml:id='l2h-2697' class="method">release</tt></b>(</nobr></td> | |
173 | <td><var></var>)</td></tr></table></dt> | |
174 | <dd> | |
175 | Releases the lock. The lock must have been acquired earlier, but not | |
176 | necessarily by the same thread. | |
177 | </dl> | |
178 | ||
179 | <P> | |
180 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
181 | <td><nobr><b><tt id='l2h-2698' xml:id='l2h-2698' class="method">locked</tt></b>(</nobr></td> | |
182 | <td><var></var>)</td></tr></table></dt> | |
183 | <dd> | |
184 | Return the status of the lock: <code>True</code> if it has been acquired by | |
185 | some thread, <code>False</code> if not. | |
186 | </dl> | |
187 | ||
188 | <P> | |
189 | <strong>Caveats:</strong> | |
190 | ||
191 | <P> | |
192 | ||
193 | <UL> | |
194 | <LI>Threads interact strangely with interrupts: the | |
195 | <tt class="exception">KeyboardInterrupt</tt> exception will be received by an | |
196 | arbitrary thread. (When the <tt class="module"><a href="module-signal.html">signal</a></tt><a id='l2h-2702' xml:id='l2h-2702'></a> | |
197 | module is available, interrupts always go to the main thread.) | |
198 | ||
199 | <P> | |
200 | </LI> | |
201 | <LI>Calling <tt class="function">sys.exit()</tt> or raising the <tt class="exception">SystemExit</tt> | |
202 | exception is equivalent to calling <tt class="function">exit()</tt>. | |
203 | ||
204 | <P> | |
205 | </LI> | |
206 | <LI>Not all built-in functions that may block waiting for I/O allow other | |
207 | threads to run. (The most popular ones (<tt class="function">time.sleep()</tt>, | |
208 | <tt class="method"><var>file</var>.read()</tt>, <tt class="function">select.select()</tt>) work as | |
209 | expected.) | |
210 | ||
211 | <P> | |
212 | </LI> | |
213 | <LI>It is not possible to interrupt the <tt class="method">acquire()</tt> method on a lock | |
214 | -- the <tt class="exception">KeyboardInterrupt</tt> exception will happen after the | |
215 | lock has been acquired. | |
216 | ||
217 | <P> | |
218 | </LI> | |
219 | <LI>When the main thread exits, it is system defined whether the other | |
220 | threads survive. On SGI IRIX using the native thread implementation, | |
221 | they survive. On most other systems, they are killed without | |
222 | executing <tt class="keyword">try</tt> ... <tt class="keyword">finally</tt> clauses or executing | |
223 | object destructors. | |
224 | <a id='l2h-2699' xml:id='l2h-2699'></a> | |
225 | <P> | |
226 | </LI> | |
227 | <LI>When the main thread exits, it does not do any of its usual cleanup | |
228 | (except that <tt class="keyword">try</tt> ... <tt class="keyword">finally</tt> clauses are honored), | |
229 | and the standard I/O files are not flushed. | |
230 | ||
231 | <P> | |
232 | </LI> | |
233 | </UL> | |
234 | ||
235 | <DIV CLASS="navigation"> | |
236 | <div class='online-navigation'> | |
237 | <p></p><hr /> | |
238 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
239 | <tr> | |
240 | <td class='online-navigation'><a rel="prev" title="7.3.1 Polling Objects" | |
241 | href="poll-objects.html"><img src='../icons/previous.png' | |
242 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
243 | <td class='online-navigation'><a rel="parent" title="7. Optional Operating System" | |
244 | href="someos.html"><img src='../icons/up.png' | |
245 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
246 | <td class='online-navigation'><a rel="next" title="7.5 threading " | |
247 | href="module-threading.html"><img src='../icons/next.png' | |
248 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
249 | <td align="center" width="100%">Python Library Reference</td> | |
250 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
251 | href="contents.html"><img src='../icons/contents.png' | |
252 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
253 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
254 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
255 | <td class='online-navigation'><a rel="index" title="Index" | |
256 | href="genindex.html"><img src='../icons/index.png' | |
257 | border='0' height='32' alt='Index' width='32' /></A></td> | |
258 | </tr></table> | |
259 | <div class='online-navigation'> | |
260 | <b class="navlabel">Previous:</b> | |
261 | <a class="sectref" rel="prev" href="poll-objects.html">7.3.1 Polling Objects</A> | |
262 | <b class="navlabel">Up:</b> | |
263 | <a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A> | |
264 | <b class="navlabel">Next:</b> | |
265 | <a class="sectref" rel="next" href="module-threading.html">7.5 threading </A> | |
266 | </div> | |
267 | </div> | |
268 | <hr /> | |
269 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
270 | </DIV> | |
271 | <!--End of Navigation Panel--> | |
272 | <ADDRESS> | |
273 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
274 | </ADDRESS> | |
275 | </BODY> | |
276 | </HTML> |