2 :mod:`threading` --- Higher-level threading interface
3 =====================================================
6 :synopsis: Higher-level threading interface.
9 This module constructs higher-level threading interfaces on top of the lower
10 level :mod:`thread` module.
11 See also the :mod:`mutex` and :mod:`Queue` modules.
13 The :mod:`dummy_threading` module is provided for situations where
14 :mod:`threading` cannot be used because :mod:`thread` is missing.
16 This module defines the following functions and objects:
19 .. function:: activeCount()
21 Return the number of :class:`Thread` objects currently alive. The returned
22 count is equal to the length of the list returned by :func:`enumerate`.
25 .. function:: Condition()
28 A factory function that returns a new condition variable object. A condition
29 variable allows one or more threads to wait until they are notified by another
33 .. function:: currentThread()
35 Return the current :class:`Thread` object, corresponding to the caller's thread
36 of control. If the caller's thread of control was not created through the
37 :mod:`threading` module, a dummy thread object with limited functionality is
41 .. function:: enumerate()
43 Return a list of all :class:`Thread` objects currently alive. The list includes
44 daemonic threads, dummy thread objects created by :func:`currentThread`, and the
45 main thread. It excludes terminated threads and threads that have not yet been
52 A factory function that returns a new event object. An event manages a flag
53 that can be set to true with the :meth:`set` method and reset to false with the
54 :meth:`clear` method. The :meth:`wait` method blocks until the flag is true.
59 A class that represents thread-local data. Thread-local data are data whose
60 values are thread specific. To manage thread-local data, just create an
61 instance of :class:`local` (or a subclass) and store attributes on it::
63 mydata = threading.local()
66 The instance's values will be different for separate threads.
68 For more details and extensive examples, see the documentation string of the
69 :mod:`_threading_local` module.
76 A factory function that returns a new primitive lock object. Once a thread has
77 acquired it, subsequent attempts to acquire it block, until it is released; any
78 thread may release it.
83 A factory function that returns a new reentrant lock object. A reentrant lock
84 must be released by the thread that acquired it. Once a thread has acquired a
85 reentrant lock, the same thread may acquire it again without blocking; the
86 thread must release it once for each time it has acquired it.
89 .. function:: Semaphore([value])
92 A factory function that returns a new semaphore object. A semaphore manages a
93 counter representing the number of :meth:`release` calls minus the number of
94 :meth:`acquire` calls, plus an initial value. The :meth:`acquire` method blocks
95 if necessary until it can return without making the counter negative. If not
96 given, *value* defaults to 1.
99 .. function:: BoundedSemaphore([value])
101 A factory function that returns a new bounded semaphore object. A bounded
102 semaphore checks to make sure its current value doesn't exceed its initial
103 value. If it does, :exc:`ValueError` is raised. In most situations semaphores
104 are used to guard resources with limited capacity. If the semaphore is released
105 too many times it's a sign of a bug. If not given, *value* defaults to 1.
110 A class that represents a thread of control. This class can be safely
111 subclassed in a limited fashion.
116 A thread that executes a function after a specified interval has passed.
119 .. function:: settrace(func)
121 .. index:: single: trace function
123 Set a trace function for all threads started from the :mod:`threading` module.
124 The *func* will be passed to :func:`sys.settrace` for each thread, before its
125 :meth:`run` method is called.
127 .. versionadded:: 2.3
130 .. function:: setprofile(func)
132 .. index:: single: profile function
134 Set a profile function for all threads started from the :mod:`threading` module.
135 The *func* will be passed to :func:`sys.setprofile` for each thread, before its
136 :meth:`run` method is called.
138 .. versionadded:: 2.3
141 .. function:: stack_size([size])
143 Return the thread stack size used when creating new threads. The optional
144 *size* argument specifies the stack size to be used for subsequently created
145 threads, and must be 0 (use platform or configured default) or a positive
146 integer value of at least 32,768 (32kB). If changing the thread stack size is
147 unsupported, a :exc:`ThreadError` is raised. If the specified stack size is
148 invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32kB
149 is currently the minimum supported stack size value to guarantee sufficient
150 stack space for the interpreter itself. Note that some platforms may have
151 particular restrictions on values for the stack size, such as requiring a
152 minimum stack size > 32kB or requiring allocation in multiples of the system
153 memory page size - platform documentation should be referred to for more
154 information (4kB pages are common; using multiples of 4096 for the stack size is
155 the suggested approach in the absence of more specific information).
156 Availability: Windows, systems with POSIX threads.
158 .. versionadded:: 2.5
160 Detailed interfaces for the objects are documented below.
162 The design of this module is loosely based on Java's threading model. However,
163 where Java makes locks and condition variables basic behavior of every object,
164 they are separate objects in Python. Python's :class:`Thread` class supports a
165 subset of the behavior of Java's Thread class; currently, there are no
166 priorities, no thread groups, and threads cannot be destroyed, stopped,
167 suspended, resumed, or interrupted. The static methods of Java's Thread class,
168 when implemented, are mapped to module-level functions.
170 All of the methods described below are executed atomically.
178 A primitive lock is a synchronization primitive that is not owned by a
179 particular thread when locked. In Python, it is currently the lowest level
180 synchronization primitive available, implemented directly by the :mod:`thread`
183 A primitive lock is in one of two states, "locked" or "unlocked". It is created
184 in the unlocked state. It has two basic methods, :meth:`acquire` and
185 :meth:`release`. When the state is unlocked, :meth:`acquire` changes the state
186 to locked and returns immediately. When the state is locked, :meth:`acquire`
187 blocks until a call to :meth:`release` in another thread changes it to unlocked,
188 then the :meth:`acquire` call resets it to locked and returns. The
189 :meth:`release` method should only be called in the locked state; it changes the
190 state to unlocked and returns immediately. If an attempt is made to release an
191 unlocked lock, a :exc:`RuntimeError` will be raised.
193 When more than one thread is blocked in :meth:`acquire` waiting for the state to
194 turn to unlocked, only one thread proceeds when a :meth:`release` call resets
195 the state to unlocked; which one of the waiting threads proceeds is not defined,
196 and may vary across implementations.
198 All methods are executed atomically.
201 .. method:: Lock.acquire([blocking=1])
203 Acquire a lock, blocking or non-blocking.
205 When invoked without arguments, block until the lock is unlocked, then set it to
206 locked, and return true.
208 When invoked with the *blocking* argument set to true, do the same thing as when
209 called without arguments, and return true.
211 When invoked with the *blocking* argument set to false, do not block. If a call
212 without an argument would block, return false immediately; otherwise, do the
213 same thing as when called without arguments, and return true.
216 .. method:: Lock.release()
220 When the lock is locked, reset it to unlocked, and return. If any other threads
221 are blocked waiting for the lock to become unlocked, allow exactly one of them
224 Do not call this method when the lock is unlocked.
226 There is no return value.
234 A reentrant lock is a synchronization primitive that may be acquired multiple
235 times by the same thread. Internally, it uses the concepts of "owning thread"
236 and "recursion level" in addition to the locked/unlocked state used by primitive
237 locks. In the locked state, some thread owns the lock; in the unlocked state,
240 To lock the lock, a thread calls its :meth:`acquire` method; this returns once
241 the thread owns the lock. To unlock the lock, a thread calls its
242 :meth:`release` method. :meth:`acquire`/:meth:`release` call pairs may be
243 nested; only the final :meth:`release` (the :meth:`release` of the outermost
244 pair) resets the lock to unlocked and allows another thread blocked in
245 :meth:`acquire` to proceed.
248 .. method:: RLock.acquire([blocking=1])
250 Acquire a lock, blocking or non-blocking.
252 When invoked without arguments: if this thread already owns the lock, increment
253 the recursion level by one, and return immediately. Otherwise, if another
254 thread owns the lock, block until the lock is unlocked. Once the lock is
255 unlocked (not owned by any thread), then grab ownership, set the recursion level
256 to one, and return. If more than one thread is blocked waiting until the lock
257 is unlocked, only one at a time will be able to grab ownership of the lock.
258 There is no return value in this case.
260 When invoked with the *blocking* argument set to true, do the same thing as when
261 called without arguments, and return true.
263 When invoked with the *blocking* argument set to false, do not block. If a call
264 without an argument would block, return false immediately; otherwise, do the
265 same thing as when called without arguments, and return true.
268 .. method:: RLock.release()
270 Release a lock, decrementing the recursion level. If after the decrement it is
271 zero, reset the lock to unlocked (not owned by any thread), and if any other
272 threads are blocked waiting for the lock to become unlocked, allow exactly one
273 of them to proceed. If after the decrement the recursion level is still
274 nonzero, the lock remains locked and owned by the calling thread.
276 Only call this method when the calling thread owns the lock. A
277 :exc:`RuntimeError` is raised if this method is called when the lock is
280 There is no return value.
283 .. _condition-objects:
288 A condition variable is always associated with some kind of lock; this can be
289 passed in or one will be created by default. (Passing one in is useful when
290 several condition variables must share the same lock.)
292 A condition variable has :meth:`acquire` and :meth:`release` methods that call
293 the corresponding methods of the associated lock. It also has a :meth:`wait`
294 method, and :meth:`notify` and :meth:`notifyAll` methods. These three must only
295 be called when the calling thread has acquired the lock, otherwise a
296 :exc:`RuntimeError` is raised.
298 The :meth:`wait` method releases the lock, and then blocks until it is awakened
299 by a :meth:`notify` or :meth:`notifyAll` call for the same condition variable in
300 another thread. Once awakened, it re-acquires the lock and returns. It is also
301 possible to specify a timeout.
303 The :meth:`notify` method wakes up one of the threads waiting for the condition
304 variable, if any are waiting. The :meth:`notifyAll` method wakes up all threads
305 waiting for the condition variable.
307 Note: the :meth:`notify` and :meth:`notifyAll` methods don't release the lock;
308 this means that the thread or threads awakened will not return from their
309 :meth:`wait` call immediately, but only when the thread that called
310 :meth:`notify` or :meth:`notifyAll` finally relinquishes ownership of the lock.
312 Tip: the typical programming style using condition variables uses the lock to
313 synchronize access to some shared state; threads that are interested in a
314 particular change of state call :meth:`wait` repeatedly until they see the
315 desired state, while threads that modify the state call :meth:`notify` or
316 :meth:`notifyAll` when they change the state in such a way that it could
317 possibly be a desired state for one of the waiters. For example, the following
318 code is a generic producer-consumer situation with unlimited buffer capacity::
322 while not an_item_is_available():
324 get_an_available_item()
329 make_an_item_available()
333 To choose between :meth:`notify` and :meth:`notifyAll`, consider whether one
334 state change can be interesting for only one or several waiting threads. E.g.
335 in a typical producer-consumer situation, adding one item to the buffer only
336 needs to wake up one consumer thread.
339 .. class:: Condition([lock])
341 If the *lock* argument is given and not ``None``, it must be a :class:`Lock` or
342 :class:`RLock` object, and it is used as the underlying lock. Otherwise, a new
343 :class:`RLock` object is created and used as the underlying lock.
346 .. method:: Condition.acquire(*args)
348 Acquire the underlying lock. This method calls the corresponding method on the
349 underlying lock; the return value is whatever that method returns.
352 .. method:: Condition.release()
354 Release the underlying lock. This method calls the corresponding method on the
355 underlying lock; there is no return value.
358 .. method:: Condition.wait([timeout])
360 Wait until notified or until a timeout occurs. If the calling thread has not
361 acquired the lock when this method is called, a :exc:`RuntimeError` is raised.
363 This method releases the underlying lock, and then blocks until it is awakened
364 by a :meth:`notify` or :meth:`notifyAll` call for the same condition variable in
365 another thread, or until the optional timeout occurs. Once awakened or timed
366 out, it re-acquires the lock and returns.
368 When the *timeout* argument is present and not ``None``, it should be a floating
369 point number specifying a timeout for the operation in seconds (or fractions
372 When the underlying lock is an :class:`RLock`, it is not released using its
373 :meth:`release` method, since this may not actually unlock the lock when it was
374 acquired multiple times recursively. Instead, an internal interface of the
375 :class:`RLock` class is used, which really unlocks it even when it has been
376 recursively acquired several times. Another internal interface is then used to
377 restore the recursion level when the lock is reacquired.
380 .. method:: Condition.notify()
382 Wake up a thread waiting on this condition, if any. Wait until notified or until
383 a timeout occurs. If the calling thread has not acquired the lock when this
384 method is called, a :exc:`RuntimeError` is raised.
386 This method wakes up one of the threads waiting for the condition variable, if
387 any are waiting; it is a no-op if no threads are waiting.
389 The current implementation wakes up exactly one thread, if any are waiting.
390 However, it's not safe to rely on this behavior. A future, optimized
391 implementation may occasionally wake up more than one thread.
393 Note: the awakened thread does not actually return from its :meth:`wait` call
394 until it can reacquire the lock. Since :meth:`notify` does not release the
395 lock, its caller should.
398 .. method:: Condition.notifyAll()
400 Wake up all threads waiting on this condition. This method acts like
401 :meth:`notify`, but wakes up all waiting threads instead of one. If the calling
402 thread has not acquired the lock when this method is called, a
403 :exc:`RuntimeError` is raised.
406 .. _semaphore-objects:
411 This is one of the oldest synchronization primitives in the history of computer
412 science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he
413 used :meth:`P` and :meth:`V` instead of :meth:`acquire` and :meth:`release`).
415 A semaphore manages an internal counter which is decremented by each
416 :meth:`acquire` call and incremented by each :meth:`release` call. The counter
417 can never go below zero; when :meth:`acquire` finds that it is zero, it blocks,
418 waiting until some other thread calls :meth:`release`.
421 .. class:: Semaphore([value])
423 The optional argument gives the initial *value* for the internal counter; it
424 defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is
428 .. method:: Semaphore.acquire([blocking])
432 When invoked without arguments: if the internal counter is larger than zero on
433 entry, decrement it by one and return immediately. If it is zero on entry,
434 block, waiting until some other thread has called :meth:`release` to make it
435 larger than zero. This is done with proper interlocking so that if multiple
436 :meth:`acquire` calls are blocked, :meth:`release` will wake exactly one of them
437 up. The implementation may pick one at random, so the order in which blocked
438 threads are awakened should not be relied on. There is no return value in this
441 When invoked with *blocking* set to true, do the same thing as when called
442 without arguments, and return true.
444 When invoked with *blocking* set to false, do not block. If a call without an
445 argument would block, return false immediately; otherwise, do the same thing as
446 when called without arguments, and return true.
449 .. method:: Semaphore.release()
451 Release a semaphore, incrementing the internal counter by one. When it was zero
452 on entry and another thread is waiting for it to become larger than zero again,
456 .. _semaphore-examples:
458 :class:`Semaphore` Example
459 ^^^^^^^^^^^^^^^^^^^^^^^^^^
461 Semaphores are often used to guard resources with limited capacity, for example,
462 a database server. In any situation where the size of the resource size is
463 fixed, you should use a bounded semaphore. Before spawning any worker threads,
464 your main thread would initialize the semaphore::
468 pool_sema = BoundedSemaphore(value=maxconnections)
470 Once spawned, worker threads call the semaphore's acquire and release methods
471 when they need to connect to the server::
475 ... use connection ...
479 The use of a bounded semaphore reduces the chance that a programming error which
480 causes the semaphore to be released more than it's acquired will go undetected.
488 This is one of the simplest mechanisms for communication between threads: one
489 thread signals an event and other threads wait for it.
491 An event object manages an internal flag that can be set to true with the
492 :meth:`set` method and reset to false with the :meth:`clear` method. The
493 :meth:`wait` method blocks until the flag is true.
498 The internal flag is initially false.
501 .. method:: Event.isSet()
503 Return true if and only if the internal flag is true.
506 .. method:: Event.set()
508 Set the internal flag to true. All threads waiting for it to become true are
509 awakened. Threads that call :meth:`wait` once the flag is true will not block at
513 .. method:: Event.clear()
515 Reset the internal flag to false. Subsequently, threads calling :meth:`wait`
516 will block until :meth:`set` is called to set the internal flag to true again.
519 .. method:: Event.wait([timeout])
521 Block until the internal flag is true. If the internal flag is true on entry,
522 return immediately. Otherwise, block until another thread calls :meth:`set` to
523 set the flag to true, or until the optional timeout occurs.
525 When the timeout argument is present and not ``None``, it should be a floating
526 point number specifying a timeout for the operation in seconds (or fractions
535 This class represents an activity that is run in a separate thread of control.
536 There are two ways to specify the activity: by passing a callable object to the
537 constructor, or by overriding the :meth:`run` method in a subclass. No other
538 methods (except for the constructor) should be overridden in a subclass. In
539 other words, *only* override the :meth:`__init__` and :meth:`run` methods of
542 Once a thread object is created, its activity must be started by calling the
543 thread's :meth:`start` method. This invokes the :meth:`run` method in a
544 separate thread of control.
546 Once the thread's activity is started, the thread is considered 'alive'. It
547 stops being alive when its :meth:`run` method terminates -- either normally, or
548 by raising an unhandled exception. The :meth:`isAlive` method tests whether the
551 Other threads can call a thread's :meth:`join` method. This blocks the calling
552 thread until the thread whose :meth:`join` method is called is terminated.
554 A thread has a name. The name can be passed to the constructor, set with the
555 :meth:`setName` method, and retrieved with the :meth:`getName` method.
557 A thread can be flagged as a "daemon thread". The significance of this flag is
558 that the entire Python program exits when only daemon threads are left. The
559 initial value is inherited from the creating thread. The flag can be set with
560 the :meth:`setDaemon` method and retrieved with the :meth:`isDaemon` method.
562 There is a "main thread" object; this corresponds to the initial thread of
563 control in the Python program. It is not a daemon thread.
565 There is the possibility that "dummy thread objects" are created. These are
566 thread objects corresponding to "alien threads", which are threads of control
567 started outside the threading module, such as directly from C code. Dummy
568 thread objects have limited functionality; they are always considered alive and
569 daemonic, and cannot be :meth:`join`\ ed. They are never deleted, since it is
570 impossible to detect the termination of alien threads.
573 .. class:: Thread(group=None, target=None, name=None, args=(), kwargs={})
575 This constructor should always be called with keyword arguments. Arguments are:
577 *group* should be ``None``; reserved for future extension when a
578 :class:`ThreadGroup` class is implemented.
580 *target* is the callable object to be invoked by the :meth:`run` method.
581 Defaults to ``None``, meaning nothing is called.
583 *name* is the thread name. By default, a unique name is constructed of the form
584 "Thread-*N*" where *N* is a small decimal number.
586 *args* is the argument tuple for the target invocation. Defaults to ``()``.
588 *kwargs* is a dictionary of keyword arguments for the target invocation.
591 If the subclass overrides the constructor, it must make sure to invoke the base
592 class constructor (``Thread.__init__()``) before doing anything else to the
596 .. method:: Thread.start()
598 Start the thread's activity.
600 It must be called at most once per thread object. It arranges for the object's
601 :meth:`run` method to be invoked in a separate thread of control.
603 This method will raise a :exc:`RuntimeException` if called more than once on the
607 .. method:: Thread.run()
609 Method representing the thread's activity.
611 You may override this method in a subclass. The standard :meth:`run` method
612 invokes the callable object passed to the object's constructor as the *target*
613 argument, if any, with sequential and keyword arguments taken from the *args*
614 and *kwargs* arguments, respectively.
617 .. method:: Thread.join([timeout])
619 Wait until the thread terminates. This blocks the calling thread until the
620 thread whose :meth:`join` method is called terminates -- either normally or
621 through an unhandled exception -- or until the optional timeout occurs.
623 When the *timeout* argument is present and not ``None``, it should be a floating
624 point number specifying a timeout for the operation in seconds (or fractions
625 thereof). As :meth:`join` always returns ``None``, you must call :meth:`isAlive`
626 after :meth:`join` to decide whether a timeout happened -- if the thread is
627 still alive, the :meth:`join` call timed out.
629 When the *timeout* argument is not present or ``None``, the operation will block
630 until the thread terminates.
632 A thread can be :meth:`join`\ ed many times.
634 :meth:`join` raises a :exc:`RuntimeError` if an attempt is made to join
635 the current thread as that would cause a deadlock. It is also an error to
636 :meth:`join` a thread before it has been started and attempts to do so
637 raises the same exception.
640 .. method:: Thread.getName()
642 Return the thread's name.
645 .. method:: Thread.setName(name)
647 Set the thread's name.
649 The name is a string used for identification purposes only. It has no semantics.
650 Multiple threads may be given the same name. The initial name is set by the
654 .. method:: Thread.getIdent()
656 Return the 'thread identifier' of this thread or None if the thread has not
657 been started. This is a nonzero integer. See the :mod:`thread` module's
658 :func:`get_ident()` function. Thread identifiers may be recycled when a
659 thread exits and another thread is created. The identifier is returned
660 even after the thread has exited.
662 .. versionadded:: 2.6
665 .. method:: Thread.isAlive()
667 Return whether the thread is alive.
669 Roughly, a thread is alive from the moment the :meth:`start` method returns
670 until its :meth:`run` method terminates. The module function :func:`enumerate`
671 returns a list of all alive threads.
674 .. method:: Thread.isDaemon()
676 Return the thread's daemon flag.
679 .. method:: Thread.setDaemon(daemonic)
681 Set the thread's daemon flag to the Boolean value *daemonic*. This must be
682 called before :meth:`start` is called, otherwise :exc:`RuntimeError` is raised.
684 The initial value is inherited from the creating thread.
686 The entire Python program exits when no alive non-daemon threads are left.
694 This class represents an action that should be run only after a certain amount
695 of time has passed --- a timer. :class:`Timer` is a subclass of :class:`Thread`
696 and as such also functions as an example of creating custom threads.
698 Timers are started, as with threads, by calling their :meth:`start` method. The
699 timer can be stopped (before its action has begun) by calling the :meth:`cancel`
700 method. The interval the timer will wait before executing its action may not be
701 exactly the same as the interval specified by the user.
708 t = Timer(30.0, hello)
709 t.start() # after 30 seconds, "hello, world" will be printed
712 .. class:: Timer(interval, function, args=[], kwargs={})
714 Create a timer that will run *function* with arguments *args* and keyword
715 arguments *kwargs*, after *interval* seconds have passed.
718 .. method:: Timer.cancel()
720 Stop the timer, and cancel the execution of the timer's action. This will only
721 work if the timer is still in its waiting stage.
726 Using locks, conditions, and semaphores in the :keyword:`with` statement
727 ------------------------------------------------------------------------
729 All of the objects provided by this module that have :meth:`acquire` and
730 :meth:`release` methods can be used as context managers for a :keyword:`with`
731 statement. The :meth:`acquire` method will be called when the block is entered,
732 and :meth:`release` will be called when the block is exited.
734 Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`,
735 :class:`Semaphore`, and :class:`BoundedSemaphore` objects may be used as
736 :keyword:`with` statement context managers. For example::
740 some_rlock = threading.RLock()
743 print "some_rlock is locked while this executes"
746 .. _threaded-imports:
748 Importing in threaded code
749 --------------------------
751 While the import machinery is thread safe, there are two key
752 restrictions on threaded imports due to inherent limitations in the way
753 that thread safety is provided:
755 * Firstly, other than in the main module, an import should not have the
756 side effect of spawning a new thread and then waiting for that thread in
757 any way. Failing to abide by this restriction can lead to a deadlock if
758 the spawned thread directly or indirectly attempts to import a module.
759 * Secondly, all import attempts must be completed before the interpreter
760 starts shutting itself down. This can be most easily achieved by only
761 performing imports from non-daemon threads created through the threading
762 module. Daemon threads and threads created directly with the thread
763 module will require some other form of synchronization to ensure they do
764 not attempt imports after system shutdown has commenced. Failure to
765 abide by this restriction will lead to intermittent exceptions and
766 crashes during interpreter shutdown (as the late imports attempt to
767 access machinery which is no longer in a valid state).