GNU Info

(python2.1-lib.info)Thread Objects

---

Prev: Event Objects Up: threading

---

Enter node , (file) or (file)node

Thread Objects
--------------

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 `run()' method
in a subclass.  No other methods (except for the constructor) should be
overridden in a subclass.  In other words, _only_  override the
`__init__()' and `run()' methods of this class.

Once a thread object is created, its activity must be started by
calling the thread's `start()' method.  This invokes the `run()' method
in a separate thread of control.

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 `run()' method terminates - either
normally, or by raising an unhandled exception.  The `isAlive()' method
tests whether the thread is alive.

Other threads can call a thread's `join()' method.  This blocks the
calling thread until the thread whose `join()' method is called is
terminated.

A thread has a name.  The name can be passed to the constructor, set
with the `setName()' method, and retrieved with the `getName()' method.

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 `setDaemon()' method and retrieved with
the `isDaemon()' method.

There is a "main thread" object; this corresponds to the initial thread
of control in the Python program.  It is not a daemon thread.

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
`join()'ed.  They are never deleted, since it is impossible to detect
the termination of alien threads.

`Thread(group=None, target=None, name=None, args=(), kwargs={})'
     This constructor should always be called with keyword arguments.
     Arguments are:

     GROUP should be `None'; reserved for future extension when a
     `ThreadGroup' class is implemented.

     TARGET is the callable object to be invoked by the `run()' method.
     Defaults to `None', meaning nothing is called.

     NAME is the thread name.  By default, a unique name is constructed
     of the form "Thread-N" where N is a small decimal number.

     ARGS is the argument tuple for the target invocation.  Defaults to
     `()'.

     KWARGS is a dictionary of keyword arguments for the target
     invocation.  Defaults to `{}'.

     If the subclass overrides the constructor, it must make sure to
     invoke the base class constructor (`Thread.__init__()') before
     doing anything else to the thread.

`start()'
     Start the thread's activity.

     This must be called at most once per thread object.  It arranges
     for the object's `run()' method to be invoked in a separate thread
     of control.

`run()'
     Method representing the thread's activity.

     You may override this method in a subclass.  The standard `run()'
     method invokes the callable object passed to the object's
     constructor as the TARGET argument, if any, with sequential and
     keyword arguments taken from the ARGS and KWARGS arguments,
     respectively.

`join([timeout])'
     Wait until the thread terminates.  This blocks the calling thread
     until the thread whose `join()' method is called terminates -
     either normally or through an unhandled exception - or until the
     optional timeout occurs.

     When the TIMEOUT argument is present and not `None', it should be
     a floating point number specifying a timeout for the operation in
     seconds (or fractions thereof).

     A thread can be `join()'ed many times.

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

     It is an error to attempt to `join()' a thread before it has been
     started.

`getName()'
     Return the thread's name.

`setName(name)'
     Set the thread's name.

     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.

`isAlive()'
     Return whether the thread is alive.

     Roughly, a thread is alive from the moment the `start()' method
     returns until its `run()' method terminates.

`isDaemon()'
     Return the thread's daemon flag.

`setDaemon(daemonic)'
     Set the thread's daemon flag to the Boolean value DAEMONIC.  This
     must be called before `start()' is called.

     The initial value is inherited from the creating thread.

     The entire Python program exits when no active non-daemon threads
     are left.