<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>7.5.6 Thread Objects </TITLE>
<META NAME="description" CONTENT="7.5.6 Thread Objects ">
<META NAME="keywords" CONTENT="lib">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="lib.css">
<LINK REL="previous" HREF="event-objects.html">
<LINK REL="up" HREF="module-threading.html">
<LINK REL="next" HREF="module-Queue.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="module-Queue.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="module-threading.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="event-objects.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="module-Queue.html">7.6 Queue  </A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="module-threading.html">7.5 threading  </A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="event-objects.html">7.5.5 Event Objects</A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION009560000000000000000"></A>
<BR>
7.5.6 Thread Objects 
</H2>

<P>
This class represents an activity that is run in a separate thread
of control.  There are two ways to specify the activity: by
passing a callable object to the constructor, or by overriding the
<tt class=method>run()</tt> method in a subclass.  No other methods (except for the
constructor) should be overridden in a subclass.  In other words, 
<i>only</i>  override the <tt class=method>__init__()</tt> and <tt class=method>run()</tt>
methods of this class.

<P>
Once a thread object is created, its activity must be started by
calling the thread's <tt class=method>start()</tt> method.  This invokes the
<tt class=method>run()</tt> method in a separate thread of control.

<P>
Once the thread's activity is started, the thread is considered
'alive' and 'active' (these concepts are almost, but not quite
exactly, the same; their definition is intentionally somewhat
vague).  It stops being alive and active when its <tt class=method>run()</tt>
method terminates - either normally, or by raising an unhandled
exception.  The <tt class=method>isAlive()</tt> method tests whether the thread is
alive.

<P>
Other threads can call a thread's <tt class=method>join()</tt> method.  This blocks
the calling thread until the thread whose <tt class=method>join()</tt> method is
called is terminated.

<P>
A thread has a name.  The name can be passed to the constructor,
set with the <tt class=method>setName()</tt> method, and retrieved with the
<tt class=method>getName()</tt> method.

<P>
A thread can be flagged as a ``daemon thread''.  The significance
of this flag is that the entire Python program exits when only
daemon threads are left.  The initial value is inherited from the
creating thread.  The flag can be set with the <tt class=method>setDaemon()</tt>
method and retrieved with the <tt class=method>getDaemon()</tt> method.

<P>
There is a ``main thread'' object; this corresponds to the
initial thread of control in the Python program.  It is not a
daemon thread.

<P>
There is the possibility that ``dummy thread objects'' are
created.  These are thread objects corresponding to ``alien
threads''.  These are threads of control started outside the
threading module, e.g. directly from C code.  Dummy thread objects
have limited functionality; they are always considered alive,
active, and daemonic, and cannot be <tt class=method>join()</tt>ed.  They are never 
deleted, since it is impossible to detect the termination of alien
threads.

<P>
<dl><dt><b><a name="l2h-1366"><tt class=class>Thread</tt></a></b> (<var>group=None, target=None, name=None,
                          args=(), kwargs={}</var>)
<dd>
This constructor should always be called with keyword
arguments.  Arguments are:

<P>
<var>group</var>
Should be <tt>None</tt>; reserved for future extension when a
<tt class=class>ThreadGroup</tt> class is implemented.

<P>
<var>target</var>
Callable object to be invoked by the <tt class=method>run()</tt> method.
Defaults to <tt>None</tt>, meaning nothing is called.

<P>
<var>name</var>
The thread name.  By default, a unique name is constructed of the form
``Thread-<var>N</var>'' where <var>N</var> is a small decimal number.

<P>
<var>args</var>
Argument tuple for the target invocation.  Defaults to <tt>()</tt>.

<P>
<var>kwargs</var>
Keyword argument dictionary for the target invocation.
Defaults to <tt>{}</tt>.

<P>
If the subclass overrides the constructor, it must make sure
to invoke the base class constructor (<tt>Thread.__init__()</tt>)
before doing anything else to the thread.
</dl>

<P>
<dl><dt><b><a name="l2h-1367"><tt class=method>start</tt></a></b> ()
<dd>
Start the thread's activity.

<P>
This must be called at most once per thread object.  It
arranges for the object's <tt class=method>run()</tt> method to be invoked in a
separate thread of control.
</dl>

<P>
<dl><dt><b><a name="l2h-1368"><tt class=method>run</tt></a></b> ()
<dd>
Method representing the thread's activity.

<P>
You may override this method in a subclass.  The standard
<tt class=method>run()</tt> method invokes the callable object passed to the object's constructor as the
<var>target</var> argument, if any, with sequential and keyword
arguments taken from the <var>args</var> and <var>kwargs</var> arguments,
respectively.
</dl>

<P>
<dl><dt><b><a name="l2h-1369"><tt class=method>join</tt></a></b> (<big>[</big><var>timeout</var><big>]</big>)
<dd>
Wait until the thread terminates.
This blocks the calling thread until the thread whose <tt class=method>join()</tt>
method is called terminates - either normally or through an
unhandled exception - or until the optional timeout occurs.

<P>
When the <var>timeout</var> argument is present and not <tt>None</tt>, it should
be a floating point number specifying a timeout for the
operation in seconds (or fractions thereof).

<P>
A thread can be <tt class=method>join()</tt>ed many times.

<P>
A thread cannot join itself because this would cause a
deadlock.

<P>
It is an error to attempt to <tt class=method>join()</tt> a thread before it has
been started.
</dl>

<P>
<dl><dt><b><a name="l2h-1370"><tt class=method>getName</tt></a></b> ()
<dd>
Return the thread's name.
</dl>

<P>
<dl><dt><b><a name="l2h-1371"><tt class=method>setName</tt></a></b> (<var>name</var>)
<dd>
Set the thread's name.

<P>
The name is a string used for identification purposes only.
It has no semantics.  Multiple threads may be given the same
name.  The initial name is set by the constructor.
</dl>

<P>
<dl><dt><b><a name="l2h-1372"><tt class=method>isAlive</tt></a></b> ()
<dd>
Return whether the thread is alive.

<P>
Roughly, a thread is alive from the moment the <tt class=method>start()</tt> method
returns until its <tt class=method>run()</tt> method terminates.
</dl>

<P>
<dl><dt><b><a name="l2h-1373"><tt class=method>isDaemon</tt></a></b> ()
<dd>
Return the thread's daemon flag.
</dl>

<P>
<dl><dt><b><a name="l2h-1374"><tt class=method>setDaemon</tt></a></b> (<var>daemonic</var>)
<dd>
Set the thread's daemon flag to the Boolean value <var>daemonic</var>.
This must be called before <tt class=method>start()</tt> is called.

<P>
The initial value is inherited from the creating thread.

<P>
The entire Python program exits when no active non-daemon
threads are left.
</dl>

<P>
<p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="module-Queue.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="module-threading.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="event-objects.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="module-Queue.html">7.6 Queue  </A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="module-threading.html">7.5 threading  </A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="event-objects.html">7.5.5 Event Objects</A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
