15.3.6 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'. It stops being alive 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'', which are threads of control started outside the threading module, such as directly from C code. Dummy thread objects have limited functionality; they are always considered alive and daemonic, and cannot be join()ed. They are never deleted, since it is impossible to detect the termination of alien threads.

class 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). As join() always returns None, you must call isAlive() to decide whether a timeout happened.

When the timeout argument is not present or None, the operation will block until the thread terminates.

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. The module function enumerate() returns a list of all alive threads.

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 alive non-daemon threads are left.

See About this document... for information on suggesting changes.