Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / thread-objects.html
CommitLineData
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="timer-objects.html" />
13<link rel="prev" href="event-objects.html" />
14<link rel="parent" href="module-threading.html" />
15<link rel="next" href="timer-objects.html" />
16<meta name='aesop' content='information' />
17<title>7.5.6 Thread Objects </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.5.5 Event Objects"
25 href="event-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.5 threading "
28 href="module-threading.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.7 Timer Objects"
31 href="timer-objects.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="event-objects.html">7.5.5 Event Objects</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="module-threading.html">7.5 threading </A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="timer-objects.html">7.5.7 Timer Objects</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H2><A NAME="SECTION009560000000000000000"></A><A NAME="thread-objects"></A>
56<BR>
577.5.6 Thread Objects
58</H2>
59
60<P>
61This class represents an activity that is run in a separate thread
62of control. There are two ways to specify the activity: by
63passing a callable object to the constructor, or by overriding the
64<tt class="method">run()</tt> method in a subclass. No other methods (except for the
65constructor) should be overridden in a subclass. In other words,
66<em>only</em> override the <tt class="method">__init__()</tt> and <tt class="method">run()</tt>
67methods of this class.
68
69<P>
70Once a thread object is created, its activity must be started by
71calling the thread's <tt class="method">start()</tt> method. This invokes the
72<tt class="method">run()</tt> method in a separate thread of control.
73
74<P>
75Once the thread's activity is started, the thread is considered
76'alive' and 'active' (these concepts are almost, but not quite
77exactly, the same; their definition is intentionally somewhat
78vague). It stops being alive and active when its <tt class="method">run()</tt>
79method terminates - either normally, or by raising an unhandled
80exception. The <tt class="method">isAlive()</tt> method tests whether the thread is
81alive.
82
83<P>
84Other threads can call a thread's <tt class="method">join()</tt> method. This blocks
85the calling thread until the thread whose <tt class="method">join()</tt> method is
86called is terminated.
87
88<P>
89A thread has a name. The name can be passed to the constructor,
90set with the <tt class="method">setName()</tt> method, and retrieved with the
91<tt class="method">getName()</tt> method.
92
93<P>
94A thread can be flagged as a ``daemon thread''. The significance
95of this flag is that the entire Python program exits when only
96daemon threads are left. The initial value is inherited from the
97creating thread. The flag can be set with the <tt class="method">setDaemon()</tt>
98method and retrieved with the <tt class="method">isDaemon()</tt> method.
99
100<P>
101There is a ``main thread'' object; this corresponds to the
102initial thread of control in the Python program. It is not a
103daemon thread.
104
105<P>
106There is the possibility that ``dummy thread objects'' are
107created. These are thread objects corresponding to ``alien
108threads''. These are threads of control started outside the
109threading module, such as directly from C code. Dummy thread objects
110have limited functionality; they are always considered alive,
111active, and daemonic, and cannot be <tt class="method">join()</tt>ed. They are never
112deleted, since it is impossible to detect the termination of alien
113threads.
114
115<P>
116<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
117 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-2738' xml:id='l2h-2738' class="class">Thread</tt></b>(</nobr></td>
118 <td><var>group=None, target=None, name=None,
119 args=(), kwargs={}</var>)</td></tr></table></dt>
120<dd>
121This constructor should always be called with keyword
122arguments. Arguments are:
123
124<P>
125<var>group</var> should be <code>None</code>; reserved for future extension when
126a <tt class="class">ThreadGroup</tt> class is implemented.
127
128<P>
129<var>target</var> is the callable object to be invoked by the
130<tt class="method">run()</tt> method. Defaults to <code>None</code>, meaning nothing is
131called.
132
133<P>
134<var>name</var> is the thread name. By default, a unique name is
135constructed of the form ``Thread-<var>N</var>'' where <var>N</var> is a small
136decimal number.
137
138<P>
139<var>args</var> is the argument tuple for the target invocation. Defaults
140to <code>()</code>.
141
142<P>
143<var>kwargs</var> is a dictionary of keyword arguments for the target
144invocation. Defaults to <code>{}</code>.
145
146<P>
147If the subclass overrides the constructor, it must make sure
148to invoke the base class constructor (<code>Thread.__init__()</code>)
149before doing anything else to the thread.
150</dl>
151
152<P>
153<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
154 <td><nobr><b><tt id='l2h-2739' xml:id='l2h-2739' class="method">start</tt></b>(</nobr></td>
155 <td><var></var>)</td></tr></table></dt>
156<dd>
157Start the thread's activity.
158
159<P>
160This must be called at most once per thread object. It
161arranges for the object's <tt class="method">run()</tt> method to be invoked in a
162separate thread of control.
163</dl>
164
165<P>
166<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
167 <td><nobr><b><tt id='l2h-2740' xml:id='l2h-2740' class="method">run</tt></b>(</nobr></td>
168 <td><var></var>)</td></tr></table></dt>
169<dd>
170Method representing the thread's activity.
171
172<P>
173You may override this method in a subclass. The standard
174<tt class="method">run()</tt> method invokes the callable object passed to the
175object's constructor as the <var>target</var> argument, if any, with
176sequential and keyword arguments taken from the <var>args</var> and
177<var>kwargs</var> arguments, respectively.
178</dl>
179
180<P>
181<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
182 <td><nobr><b><tt id='l2h-2741' xml:id='l2h-2741' class="method">join</tt></b>(</nobr></td>
183 <td><var></var><big>[</big><var>timeout</var><big>]</big><var></var>)</td></tr></table></dt>
184<dd>
185Wait until the thread terminates.
186This blocks the calling thread until the thread whose <tt class="method">join()</tt>
187method is called terminates - either normally or through an
188unhandled exception - or until the optional timeout occurs.
189
190<P>
191When the <var>timeout</var> argument is present and not <code>None</code>, it
192should be a floating point number specifying a timeout for the
193operation in seconds (or fractions thereof). As <tt class="method">join()</tt> always
194returns <code>None</code>, you must call <tt class="method">isAlive()</tt> to decide whether
195a timeout happened.
196
197<P>
198When the <var>timeout</var> argument is not present or <code>None</code>, the
199operation will block until the thread terminates.
200
201<P>
202A thread can be <tt class="method">join()</tt>ed many times.
203
204<P>
205A thread cannot join itself because this would cause a
206deadlock.
207
208<P>
209It is an error to attempt to <tt class="method">join()</tt> a thread before it has
210been started.
211</dl>
212
213<P>
214<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
215 <td><nobr><b><tt id='l2h-2742' xml:id='l2h-2742' class="method">getName</tt></b>(</nobr></td>
216 <td><var></var>)</td></tr></table></dt>
217<dd>
218Return the thread's name.
219</dl>
220
221<P>
222<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
223 <td><nobr><b><tt id='l2h-2743' xml:id='l2h-2743' class="method">setName</tt></b>(</nobr></td>
224 <td><var>name</var>)</td></tr></table></dt>
225<dd>
226Set the thread's name.
227
228<P>
229The name is a string used for identification purposes only.
230It has no semantics. Multiple threads may be given the same
231name. The initial name is set by the constructor.
232</dl>
233
234<P>
235<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
236 <td><nobr><b><tt id='l2h-2744' xml:id='l2h-2744' class="method">isAlive</tt></b>(</nobr></td>
237 <td><var></var>)</td></tr></table></dt>
238<dd>
239Return whether the thread is alive.
240
241<P>
242Roughly, a thread is alive from the moment the <tt class="method">start()</tt> method
243returns until its <tt class="method">run()</tt> method terminates.
244</dl>
245
246<P>
247<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
248 <td><nobr><b><tt id='l2h-2745' xml:id='l2h-2745' class="method">isDaemon</tt></b>(</nobr></td>
249 <td><var></var>)</td></tr></table></dt>
250<dd>
251Return the thread's daemon flag.
252</dl>
253
254<P>
255<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
256 <td><nobr><b><tt id='l2h-2746' xml:id='l2h-2746' class="method">setDaemon</tt></b>(</nobr></td>
257 <td><var>daemonic</var>)</td></tr></table></dt>
258<dd>
259Set the thread's daemon flag to the Boolean value <var>daemonic</var>.
260This must be called before <tt class="method">start()</tt> is called.
261
262<P>
263The initial value is inherited from the creating thread.
264
265<P>
266The entire Python program exits when no active non-daemon
267threads are left.
268</dl>
269
270<P>
271
272<DIV CLASS="navigation">
273<div class='online-navigation'>
274<p></p><hr />
275<table align="center" width="100%" cellpadding="0" cellspacing="2">
276<tr>
277<td class='online-navigation'><a rel="prev" title="7.5.5 Event Objects"
278 href="event-objects.html"><img src='../icons/previous.png'
279 border='0' height='32' alt='Previous Page' width='32' /></A></td>
280<td class='online-navigation'><a rel="parent" title="7.5 threading "
281 href="module-threading.html"><img src='../icons/up.png'
282 border='0' height='32' alt='Up One Level' width='32' /></A></td>
283<td class='online-navigation'><a rel="next" title="7.5.7 Timer Objects"
284 href="timer-objects.html"><img src='../icons/next.png'
285 border='0' height='32' alt='Next Page' width='32' /></A></td>
286<td align="center" width="100%">Python Library Reference</td>
287<td class='online-navigation'><a rel="contents" title="Table of Contents"
288 href="contents.html"><img src='../icons/contents.png'
289 border='0' height='32' alt='Contents' width='32' /></A></td>
290<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
291 border='0' height='32' alt='Module Index' width='32' /></a></td>
292<td class='online-navigation'><a rel="index" title="Index"
293 href="genindex.html"><img src='../icons/index.png'
294 border='0' height='32' alt='Index' width='32' /></A></td>
295</tr></table>
296<div class='online-navigation'>
297<b class="navlabel">Previous:</b>
298<a class="sectref" rel="prev" href="event-objects.html">7.5.5 Event Objects</A>
299<b class="navlabel">Up:</b>
300<a class="sectref" rel="parent" href="module-threading.html">7.5 threading </A>
301<b class="navlabel">Next:</b>
302<a class="sectref" rel="next" href="timer-objects.html">7.5.7 Timer Objects</A>
303</div>
304</div>
305<hr />
306<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
307</DIV>
308<!--End of Navigation Panel-->
309<ADDRESS>
310See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
311</ADDRESS>
312</BODY>
313</HTML>