Note

Starting with Python 2.6, this module providesPEP 8 compliant aliases andproperties to replace thecamelCase names that were inspired by Java’sthreading API. This updated API is compatible with that of themultiprocessing module. However, no schedule has been set for thedeprecation of thecamelCase names and they remain fully supported inboth Python 2.x and 3.x.

Note

Starting with Python 2.5, several Thread methods raiseRuntimeErrorinstead ofAssertionError if called erroneously.

CPython implementation detail: In CPython, due to theGlobal Interpreter Lock, only one threadcan execute Python code at once (even though certain performance-orientedlibraries might overcome this limitation).If you want your application to make better use of the computationalresources of multi-core machines, you are advised to usemultiprocessing. However, threading is still an appropriate modelif you want to run multiple I/O-bound tasks simultaneously.

16.2.1.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 theconstructor, or by overriding therun() method in a subclass. No othermethods (except for the constructor) should be overridden in a subclass. Inother words,only override the__init__() andrun() methods ofthis class.

Once a thread object is created, its activity must be started by calling thethread’sstart() method. This invokes therun() method in aseparate thread of control.

Once the thread’s activity is started, the thread is considered ‘alive’. Itstops being alive when itsrun() method terminates – either normally, orby raising an unhandled exception. Theis_alive() method tests whether thethread is alive.

Other threads can call a thread’sjoin() method. This blocks the callingthread until the thread whosejoin() method is called is terminated.

A thread has a name. The name can be passed to the constructor, and read orchanged through thename attribute.

A thread can be flagged as a “daemon thread”. The significance of this flag isthat the entire Python program exits when only daemon threads are left. Theinitial value is inherited from the creating thread. The flag can be setthrough thedaemon property.

There is a “main thread” object; this corresponds to the initial thread ofcontrol in the Python program. It is not a daemon thread.

There is the possibility that “dummy thread objects” are created. These arethread objects corresponding to “alien threads”, which are threads of controlstarted outside the threading module, such as directly from C code. Dummythread objects have limited functionality; they are always considered alive anddaemonic, and cannot bejoin()ed. They are never deleted, since it isimpossible to detect the termination of alien threads.

classthreading.Thread(group=None,target=None,name=None,args=(),kwargs={})¶

This constructor should always be called with keyword arguments. Argumentsare:

group should beNone; reserved for future extension when aThreadGroup class is implemented.

target is the callable object to be invoked by therun() method.Defaults toNone, meaning nothing is called.

name is the thread name. By default, a unique name is constructed of theform “Thread-N” whereN 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 thebase class constructor (Thread.__init__()) before doing anything else tothe thread.

start()¶

Start the thread’s activity.

It must be called at most once per thread object. It arranges for theobject’srun() method to be invoked in a separate thread of control.

This method will raise aRuntimeError if called more than onceon the same thread object.

run()¶

Method representing the thread’s activity.

You may override this method in a subclass. The standardrun()method invokes the callable object passed to the object’s constructor asthetarget argument, if any, with sequential and keyword arguments takenfrom theargs andkwargs arguments, respectively.

join([timeout])¶

Wait until the thread terminates. This blocks the calling thread until thethread whosejoin() method is called terminates – either normallyor through an unhandled exception – or until the optional timeout occurs.

When thetimeout argument is present and notNone, it should be afloating point number specifying a timeout for the operation in seconds(or fractions thereof). Asjoin() always returnsNone, you mustcallisAlive() afterjoin() to decide whether a timeouthappened – if the thread is still alive, thejoin() call timed out.

When thetimeout argument is not present orNone, the operation willblock until the thread terminates.

A thread can bejoin()ed many times.

join() raises aRuntimeError if an attempt is made to jointhe current thread as that would cause a deadlock. It is also an error tojoin() a thread before it has been started and attempts to do soraises the same exception.

name¶

A string used for identification purposes only. It has no semantics.Multiple threads may be given the same name. The initial name is set bythe constructor.

New in version 2.6.

getName()¶

setName()¶

Pre-2.6 API forname.

ident¶

The ‘thread identifier’ of this thread orNone if the thread has notbeen started. This is a nonzero integer. See thethread.get_ident() function. Thread identifiers may be recycledwhen a thread exits and another thread is created. The identifier isavailable even after the thread has exited.

New in version 2.6.

is_alive()¶

isAlive()¶

Return whether the thread is alive.

This method returnsTrue just before therun() method startsuntil just after therun() method terminates. The module functionenumerate() returns a list of all alive threads.

Changed in version 2.6:Addedis_alive() spelling.

daemon¶

A boolean value indicating whether this thread is a daemon thread (True)or not (False). This must be set beforestart() is called,otherwiseRuntimeError is raised. Its initial value is inheritedfrom the creating thread; the main thread is not a daemon thread andtherefore all threads created in the main thread default todaemon=False.

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

New in version 2.6.

isDaemon()¶

setDaemon()¶

Pre-2.6 API fordaemon.

16.2.2.Lock Objects¶

A primitive lock is a synchronization primitive that is not owned by aparticular thread when locked. In Python, it is currently the lowest levelsynchronization primitive available, implemented directly by thethreadextension module.

A primitive lock is in one of two states, “locked” or “unlocked”. It is createdin the unlocked state. It has two basic methods,acquire() andrelease(). When the state is unlocked,acquire() changes the stateto locked and returns immediately. When the state is locked,acquire()blocks until a call torelease() in another thread changes it to unlocked,then theacquire() call resets it to locked and returns. Therelease() method should only be called in the locked state; it changes thestate to unlocked and returns immediately. If an attempt is made to release anunlocked lock, aThreadError will be raised.

When more than one thread is blocked inacquire() waiting for the state toturn to unlocked, only one thread proceeds when arelease() call resetsthe state to unlocked; which one of the waiting threads proceeds is not defined,and may vary across implementations.

All methods are executed atomically.

Lock.acquire([blocking])¶

Acquire a lock, blocking or non-blocking.

When invoked with theblocking argument set toTrue (the default),block until the lock is unlocked, then set it to locked and returnTrue.

When invoked with theblocking argument set toFalse, do not block.If a call withblocking set toTrue would block, returnFalseimmediately; otherwise, set the lock to locked and returnTrue.

Lock.release()¶

Release a lock.

When the lock is locked, reset it to unlocked, and return. If any other threadsare blocked waiting for the lock to become unlocked, allow exactly one of themto proceed.

When invoked on an unlocked lock, aThreadError is raised.

There is no return value.

locked()¶

Return true if the lock is acquired.

16.2.3.RLock Objects¶

A reentrant lock is a synchronization primitive that may be acquired multipletimes by the same thread. Internally, it uses the concepts of “owning thread”and “recursion level” in addition to the locked/unlocked state used by primitivelocks. In the locked state, some thread owns the lock; in the unlocked state,no thread owns it.

To lock the lock, a thread calls itsacquire() method; this returns oncethe thread owns the lock. To unlock the lock, a thread calls itsrelease() method.acquire()/release() call pairs may benested; only the finalrelease() (therelease() of the outermostpair) resets the lock to unlocked and allows another thread blocked inacquire() to proceed.

RLock.acquire([blocking=1])¶

Acquire a lock, blocking or non-blocking.

When invoked without arguments: if this thread already owns the lock, incrementthe recursion level by one, and return immediately. Otherwise, if anotherthread owns the lock, block until the lock is unlocked. Once the lock isunlocked (not owned by any thread), then grab ownership, set the recursion levelto one, and return. If more than one thread is blocked waiting until the lockis unlocked, only one at a time will be able to grab ownership of the lock.There is no return value in this case.

When invoked with theblocking argument set to true, do the same thing as whencalled without arguments, and return true.

When invoked with theblocking argument set to false, do not block. If a callwithout an argument would block, return false immediately; otherwise, do thesame thing as when called without arguments, and return true.

RLock.release()¶

Release a lock, decrementing the recursion level. If after the decrement it iszero, reset the lock to unlocked (not owned by any thread), and if any otherthreads are blocked waiting for the lock to become unlocked, allow exactly oneof them to proceed. If after the decrement the recursion level is stillnonzero, the lock remains locked and owned by the calling thread.

Only call this method when the calling thread owns the lock. ARuntimeError is raised if this method is called when the lock isunlocked.

There is no return value.

16.2.4.Condition Objects¶

A condition variable is always associated with some kind of lock; this can bepassed in or one will be created by default. (Passing one in is useful whenseveral condition variables must share the same lock.)

A condition variable hasacquire() andrelease() methods that callthe corresponding methods of the associated lock. It also has await()method, andnotify() andnotifyAll() methods. These three must onlybe called when the calling thread has acquired the lock, otherwise aRuntimeError is raised.

Thewait() method releases the lock, and then blocks until it is awakenedby anotify() ornotifyAll() call for the same condition variable inanother thread. Once awakened, it re-acquires the lock and returns. It is alsopossible to specify a timeout.

Thenotify() method wakes up one of the threads waiting for the conditionvariable, if any are waiting. ThenotifyAll() method wakes up all threadswaiting for the condition variable.

Note: thenotify() andnotifyAll() methods don’t release the lock;this means that the thread or threads awakened will not return from theirwait() call immediately, but only when the thread that callednotify() ornotifyAll() finally relinquishes ownership of the lock.

Tip: the typical programming style using condition variables uses the lock tosynchronize access to some shared state; threads that are interested in aparticular change of state callwait() repeatedly until they see thedesired state, while threads that modify the state callnotify() ornotifyAll() when they change the state in such a way that it couldpossibly be a desired state for one of the waiters. For example, the followingcode is a generic producer-consumer situation with unlimited buffer capacity:

# Consume one itemcv.acquire()whilenotan_item_is_available():cv.wait()get_an_available_item()cv.release()# Produce one itemcv.acquire()make_an_item_available()cv.notify()cv.release()

To choose betweennotify() andnotifyAll(), consider whether onestate change can be interesting for only one or several waiting threads. E.g.in a typical producer-consumer situation, adding one item to the buffer onlyneeds to wake up one consumer thread.

classthreading.Condition([lock])¶

If thelock argument is given and notNone, it must be aLockorRLock object, and it is used as the underlying lock. Otherwise,a newRLock object is created and used as the underlying lock.

acquire(*args)¶

Acquire the underlying lock. This method calls the corresponding method onthe underlying lock; the return value is whatever that method returns.

release()¶

Release the underlying lock. This method calls the corresponding method onthe underlying lock; there is no return value.

wait([timeout])¶

Wait until notified or until a timeout occurs. If the calling thread has notacquired the lock when this method is called, aRuntimeError is raised.

This method releases the underlying lock, and then blocks until it isawakened by anotify() ornotifyAll() call for the samecondition variable in another thread, or until the optional timeoutoccurs. Once awakened or timed out, it re-acquires the lock and returns.

When thetimeout argument is present and notNone, it should be afloating point number specifying a timeout for the operation in seconds(or fractions thereof).

When the underlying lock is anRLock, it is not released usingitsrelease() method, since this may not actually unlock the lockwhen it was acquired multiple times recursively. Instead, an internalinterface of theRLock class is used, which really unlocks iteven when it has been recursively acquired several times. Another internalinterface is then used to restore the recursion level when the lock isreacquired.

notify(n=1)¶

By default, wake up one thread waiting on this condition, if any. If thecalling thread has not acquired the lock when this method is called, aRuntimeError is raised.

This method wakes up at mostn of the threads waiting for the conditionvariable; it is a no-op if no threads are waiting.

The current implementation wakes up exactlyn threads, if at leastnthreads are waiting. However, it’s not safe to rely on this behavior.A future, optimized implementation may occasionally wake up more thann threads.

Note: an awakened thread does not actually return from itswait()call until it can reacquire the lock. Sincenotify() does notrelease the lock, its caller should.

notify_all()¶

notifyAll()¶

Wake up all threads waiting on this condition. This method acts likenotify(), but wakes up all waiting threads instead of one. If thecalling thread has not acquired the lock when this method is called, aRuntimeError is raised.

Changed in version 2.6:Addednotify_all() spelling.

16.2.5.Semaphore Objects¶

This is one of the oldest synchronization primitives in the history of computerscience, invented by the early Dutch computer scientist Edsger W. Dijkstra (heusedP() andV() instead ofacquire() andrelease()).

A semaphore manages an internal counter which is decremented by eachacquire() call and incremented by eachrelease() call. The countercan never go below zero; whenacquire() finds that it is zero, it blocks,waiting until some other thread callsrelease().

classthreading.Semaphore([value])¶

The optional argument gives the initialvalue for the internal counter; itdefaults to1. If thevalue given is less than 0,ValueError israised.

acquire([blocking])¶

Acquire a semaphore.

When invoked without arguments: if the internal counter is larger thanzero on entry, decrement it by one and return immediately. If it is zeroon entry, block, waiting until some other thread has calledrelease() to make it larger than zero. This is done with properinterlocking so that if multipleacquire() calls are blocked,release() will wake exactly one of them up. The implementation maypick one at random, so the order in which blocked threads are awakenedshould not be relied on. There is no return value in this case.

When invoked withblocking set to true, do the same thing as when calledwithout arguments, and return true.

When invoked withblocking set to false, do not block. If a callwithout an argument would block, return false immediately; otherwise, dothe same thing as when called without arguments, and return true.

release()¶

Release a semaphore, incrementing the internal counter by one. When itwas zero on entry and another thread is waiting for it to become largerthan zero again, wake up that thread.

maxconnections=5...pool_sema=BoundedSemaphore(value=maxconnections)

pool_sema.acquire()conn=connectdb()...useconnection...conn.close()pool_sema.release()

16.2.6.Event Objects¶

This is one of the simplest mechanisms for communication between threads: onethread signals an event and other threads wait for it.

An event object manages an internal flag that can be set to true with theset() method and reset to false with theclear()method. Thewait() method blocks until the flag is true.

classthreading.Event¶

The internal flag is initially false.

is_set()¶

isSet()¶

Return true if and only if the internal flag is true.

Changed in version 2.6:Addedis_set() spelling.

set()¶

Set the internal flag to true. All threads waiting for it to become trueare awakened. Threads that callwait() once the flag is true willnot block at all.

clear()¶

Reset the internal flag to false. Subsequently, threads callingwait() will block untilset() is called to set the internalflag to true again.

wait([timeout])¶

Block until the internal flag is true. If the internal flag is true onentry, return immediately. Otherwise, block until another thread callsset() to set the flag to true, or until the optional timeoutoccurs.

When the timeout argument is present and notNone, it should be afloating point number specifying a timeout for the operation in seconds(or fractions thereof).

This method returns the internal flag on exit, so it will always returnTrue except if a timeout is given and the operation times out.

Changed in version 2.7:Previously, the method always returnedNone.

16.2.7.Timer Objects¶

This class represents an action that should be run only after a certain amountof time has passed — a timer.Timer is a subclass ofThreadand as such also functions as an example of creating custom threads.

Timers are started, as with threads, by calling theirstart()method. The timer can be stopped (before its action has begun) by calling thecancel() method. The interval the timer will wait beforeexecuting its action may not be exactly the same as the interval specified bythe user.

For example:

defhello():print"hello, world"t=Timer(30.0,hello)t.start()# after 30 seconds, "hello, world" will be printed

classthreading.Timer(interval,function,args=[],kwargs={})¶

Create a timer that will runfunction with argumentsargs and keywordargumentskwargs, afterinterval seconds have passed.

cancel()¶

Stop the timer, and cancel the execution of the timer’s action. This willonly work if the timer is still in its waiting stage.

16.2.8.Using locks, conditions, and semaphores in thewith statement¶

All of the objects provided by this module that haveacquire() andrelease() methods can be used as context managers for awithstatement. Theacquire() method will be called when the block is entered,andrelease() will be called when the block is exited.

Currently,Lock,RLock,Condition,Semaphore, andBoundedSemaphore objects may be used aswith statement context managers. For example:

importthreadingsome_rlock=threading.RLock()withsome_rlock:print"some_rlock is locked while this executes"

16.2.9.Importing in threaded code¶

While the import machinery is thread-safe, there are two key restrictions onthreaded imports due to inherent limitations in the way that thread-safety isprovided:

• Firstly, other than in the main module, an import should not have theside effect of spawning a new thread and then waiting for that thread inany way. Failing to abide by this restriction can lead to a deadlock ifthe spawned thread directly or indirectly attempts to import a module.

• Secondly, all import attempts must be completed before the interpreterstarts shutting itself down. This can be most easily achieved by onlyperforming imports from non-daemon threads created through the threadingmodule. Daemon threads and threads created directly with the threadmodule will require some other form of synchronization to ensure they donot attempt imports after system shutdown has commenced. Failure toabide by this restriction will lead to intermittent exceptions andcrashes during interpreter shutdown (as the late imports attempt toaccess machinery which is no longer in a valid state).