rest25/library/threading.rst => rest262/library/threading.rst
n1- 
2:mod:`threading` --- Higher-level threading interface
3=====================================================
4
5.. module:: threading
6   :synopsis: Higher-level threading interface.
7
8
9This module constructs higher-level threading interfaces on top of the  lower
10level :mod:`thread` module.
n10+See also the :mod:`mutex` and :mod:`Queue` modules.
11
12The :mod:`dummy_threading` module is provided for situations where
13:mod:`threading` cannot be used because :mod:`thread` is missing.
14
n15+.. note::
16+ 
17+   Starting with Python 2.6, this module provides PEP 8 compliant aliases and
18+   properties to replace the ``camelCase`` names that were inspired by Java's
19+   threading API. This updated API is compatible with that of the
20+   :mod:`multiprocessing` module. However, no schedule has been set for the
21+   deprecation of the ``camelCase`` names and they remain fully supported in
22+   both Python 2.x and 3.x.
23+ 
24+.. note::
25+ 
26+   Starting with Python 2.5, several Thread methods raise :exc:`RuntimeError`
27+   instead of :exc:`AssertionError` if called erroneously.
28+ 
29+ 
15This module defines the following functions and objects:
16
n17- 
18-.. function:: activeCount()
32+.. function:: active_count()
33+              activeCount()
19
n20-   Return the number of currently active :class:`Thread` objects. The returned
n35+   Return the number of :class:`Thread` objects currently alive.  The returned
21-   count is equal to the length of the list returned by :func:`enumerate`. A
36+   count is equal to the length of the list returned by :func:`enumerate`.
22-   function that returns the number of currently active threads.
23
24
25.. function:: Condition()
n40+   :noindex:
26
27   A factory function that returns a new condition variable object. A condition
28   variable allows one or more threads to wait until they are notified by another
29   thread.
30
31
n32-.. function:: currentThread()
n47+.. function:: current_thread()
48+              currentThread()
33
34   Return the current :class:`Thread` object, corresponding to the caller's thread
35   of control.  If the caller's thread of control was not created through the
36   :mod:`threading` module, a dummy thread object with limited functionality is
37   returned.
38
39
40.. function:: enumerate()
41
n42-   Return a list of all currently active :class:`Thread` objects. The list includes
n58+   Return a list of all :class:`Thread` objects currently alive.  The list
43-   daemonic threads, dummy thread objects created by :func:`currentThread`, and the
59+   includes daemonic threads, dummy thread objects created by
44-   main thread.  It excludes terminated threads and threads that have not yet been
60+   :func:`current_thread`, and the main thread.  It excludes terminated threads
45-   started.
61+   and threads that have not yet been started.
46
47
48.. function:: Event()
n65+   :noindex:
49
50   A factory function that returns a new event object.  An event manages a flag
51   that can be set to true with the :meth:`set` method and reset to false with the
52   :meth:`clear` method.  The :meth:`wait` method blocks until the flag is true.
53
54
55.. class:: local
56
80
81   A factory function that returns a new reentrant lock object. A reentrant lock
82   must be released by the thread that acquired it. Once a thread has acquired a
83   reentrant lock, the same thread may acquire it again without blocking; the
84   thread must release it once for each time it has acquired it.
85
86
87.. function:: Semaphore([value])
n105+   :noindex:
88
89   A factory function that returns a new semaphore object.  A semaphore manages a
90   counter representing the number of :meth:`release` calls minus the number of
91   :meth:`acquire` calls, plus an initial value. The :meth:`acquire` method blocks
92   if necessary until it can return without making the counter negative.  If not
93   given, *value* defaults to 1.
94
95
162subset of the behavior of Java's Thread class; currently, there are no
163priorities, no thread groups, and threads cannot be destroyed, stopped,
164suspended, resumed, or interrupted.  The static methods of Java's Thread class,
165when implemented, are mapped to module-level functions.
166
167All of the methods described below are executed atomically.
168
169
n188+.. _thread-objects:
189+ 
190+Thread Objects
191+--------------
192+ 
193+This class represents an activity that is run in a separate thread of control.
194+There are two ways to specify the activity: by passing a callable object to the
195+constructor, or by overriding the :meth:`run` method in a subclass.  No other
196+methods (except for the constructor) should be overridden in a subclass.  In
197+other words,  *only*  override the :meth:`__init__` and :meth:`run` methods of
198+this class.
199+ 
200+Once a thread object is created, its activity must be started by calling the
201+thread's :meth:`start` method.  This invokes the :meth:`run` method in a
202+separate thread of control.
203+ 
204+Once the thread's activity is started, the thread is considered 'alive'. It
205+stops being alive when its :meth:`run` method terminates -- either normally, or
206+by raising an unhandled exception.  The :meth:`is_alive` method tests whether the
207+thread is alive.
208+ 
209+Other threads can call a thread's :meth:`join` method.  This blocks the calling
210+thread until the thread whose :meth:`join` method is called is terminated.
211+ 
212+A thread has a name.  The name can be passed to the constructor, and read or
213+changed through the :attr:`name` attribute.
214+ 
215+A thread can be flagged as a "daemon thread".  The significance of this flag is
216+that the entire Python program exits when only daemon threads are left.  The
217+initial value is inherited from the creating thread.  The flag can be set
218+through the :attr:`daemon` property.
219+ 
220+There is a "main thread" object; this corresponds to the initial thread of
221+control in the Python program.  It is not a daemon thread.
222+ 
223+There is the possibility that "dummy thread objects" are created. These are
224+thread objects corresponding to "alien threads", which are threads of control
225+started outside the threading module, such as directly from C code.  Dummy
226+thread objects have limited functionality; they are always considered alive and
227+daemonic, and cannot be :meth:`join`\ ed.  They are never deleted, since it is
228+impossible to detect the termination of alien threads.
229+ 
230+ 
231+.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={})
232+ 
233+   This constructor should always be called with keyword arguments.  Arguments are:
234+ 
235+   *group* should be ``None``; reserved for future extension when a
236+   :class:`ThreadGroup` class is implemented.
237+ 
238+   *target* is the callable object to be invoked by the :meth:`run` method.
239+   Defaults to ``None``, meaning nothing is called.
240+ 
241+   *name* is the thread name.  By default, a unique name is constructed of the form
242+   "Thread-*N*" where *N* is a small decimal number.
243+ 
244+   *args* is the argument tuple for the target invocation.  Defaults to ``()``.
245+ 
246+   *kwargs* is a dictionary of keyword arguments for the target invocation.
247+   Defaults to ``{}``.
248+ 
249+   If the subclass overrides the constructor, it must make sure to invoke the base
250+   class constructor (``Thread.__init__()``) before doing anything else to the
251+   thread.
252+ 
253+ 
254+.. method:: Thread.start()
255+ 
256+   Start the thread's activity.
257+ 
258+   It must be called at most once per thread object.  It arranges for the object's
259+   :meth:`run` method to be invoked in a separate thread of control.
260+ 
261+   This method will raise a :exc:`RuntimeException` if called more than once on the
262+   same thread object.
263+ 
264+ 
265+.. method:: Thread.run()
266+ 
267+   Method representing the thread's activity.
268+ 
269+   You may override this method in a subclass.  The standard :meth:`run` method
270+   invokes the callable object passed to the object's constructor as the *target*
271+   argument, if any, with sequential and keyword arguments taken from the *args*
272+   and *kwargs* arguments, respectively.
273+ 
274+ 
275+.. method:: Thread.join([timeout])
276+ 
277+   Wait until the thread terminates. This blocks the calling thread until the
278+   thread whose :meth:`join` method is called terminates -- either normally or
279+   through an unhandled exception -- or until the optional timeout occurs.
280+ 
281+   When the *timeout* argument is present and not ``None``, it should be a floating
282+   point number specifying a timeout for the operation in seconds (or fractions
283+   thereof). As :meth:`join` always returns ``None``, you must call :meth:`isAlive`
284+   after :meth:`join` to decide whether a timeout happened -- if the thread is
285+   still alive, the :meth:`join` call timed out.
286+ 
287+   When the *timeout* argument is not present or ``None``, the operation will block
288+   until the thread terminates.
289+ 
290+   A thread can be :meth:`join`\ ed many times.
291+ 
292+   :meth:`join` raises a :exc:`RuntimeError` if an attempt is made to join
293+   the current thread as that would cause a deadlock. It is also an error to
294+   :meth:`join` a thread before it has been started and attempts to do so
295+   raises the same exception.
296+ 
297+ 
298+.. method:: Thread.getName()
299+            Thread.setName()
300+ 
301+   Old API for :attr:`~Thread.name`.
302+ 
303+ 
304+.. attribute:: Thread.name
305+ 
306+   A string used for identification purposes only. It has no semantics.
307+   Multiple threads may be given the same name.  The initial name is set by the
308+   constructor.
309+ 
310+ 
311+.. attribute:: Thread.ident
312+ 
313+   The 'thread identifier' of this thread or ``None`` if the thread has not been
314+   started.  This is a nonzero integer.  See the :func:`thread.get_ident()`
315+   function.  Thread identifiers may be recycled when a thread exits and another
316+   thread is created.  The identifier is available even after the thread has
317+   exited.
318+ 
319+   .. versionadded:: 2.6
320+ 
321+ 
322+.. method:: Thread.is_alive()
323+            Thread.isAlive()
324+ 
325+   Return whether the thread is alive.
326+ 
327+   Roughly, a thread is alive from the moment the :meth:`start` method returns
328+   until its :meth:`run` method terminates. The module function :func:`enumerate`
329+   returns a list of all alive threads.
330+ 
331+ 
332+.. method:: Thread.isDaemon()
333+            Thread.setDaemon()
334+ 
335+   Old API for :attr:`~Thread.daemon`.
336+ 
337+ 
338+.. attribute:: Thread.daemon
339+ 
340+   A boolean value indicating whether this thread is a daemon thread (True) or
341+   not (False).  This must be set before :meth:`start` is called, otherwise
342+   :exc:`RuntimeError` is raised.  Its initial value is inherited from the
343+   creating thread; the main thread is not a daemon thread and therefore all
344+   threads created in the main thread default to :attr:`daemon` = ``False``.
345+ 
346+   The entire Python program exits when no alive non-daemon threads are left.
347+ 
348+ 
170.. _lock-objects:
171
172Lock Objects
173------------
174
175A primitive lock is a synchronization primitive that is not owned by a
176particular thread when locked.  In Python, it is currently the lowest level
177synchronization primitive available, implemented directly by the :mod:`thread`
179
180A primitive lock is in one of two states, "locked" or "unlocked". It is created
181in the unlocked state.  It has two basic methods, :meth:`acquire` and
182:meth:`release`.  When the state is unlocked, :meth:`acquire` changes the state
183to locked and returns immediately.  When the state is locked, :meth:`acquire`
184blocks until a call to :meth:`release` in another thread changes it to unlocked,
185then the :meth:`acquire` call resets it to locked and returns.  The
186:meth:`release` method should only be called in the locked state; it changes the
n187-state to unlocked and returns immediately.  When more than one thread is blocked
n366+state to unlocked and returns immediately. If an attempt is made to release an
188-in :meth:`acquire` waiting for the state to turn to unlocked, only one thread
367+unlocked lock, a :exc:`RuntimeError` will be raised.
189-proceeds when a :meth:`release` call resets the state to unlocked; which one of
368+ 
190-the waiting threads proceeds is not defined, and may vary across
369+When more than one thread is blocked in :meth:`acquire` waiting for the state to
191-implementations.
370+turn to unlocked, only one thread proceeds when a :meth:`release` call resets
371+the state to unlocked; which one of the waiting threads proceeds is not defined,
372+and may vary across implementations.
192
193All methods are executed atomically.
194
195
n196-.. method:: XXX Class.acquire([blocking\ ``= 1``])
n377+.. method:: Lock.acquire([blocking=1])
197
198   Acquire a lock, blocking or non-blocking.
199
200   When invoked without arguments, block until the lock is unlocked, then set it to
201   locked, and return true.
202
203   When invoked with the *blocking* argument set to true, do the same thing as when
204   called without arguments, and return true.
205
206   When invoked with the *blocking* argument set to false, do not block.  If a call
207   without an argument would block, return false immediately; otherwise, do the
208   same thing as when called without arguments, and return true.
209
210
n211-.. method:: XXX Class.release()
n392+.. method:: Lock.release()
212
213   Release a lock.
214
215   When the lock is locked, reset it to unlocked, and return.  If any other threads
216   are blocked waiting for the lock to become unlocked, allow exactly one of them
217   to proceed.
218
219   Do not call this method when the lock is unlocked.
235To lock the lock, a thread calls its :meth:`acquire` method; this returns once
236the thread owns the lock.  To unlock the lock, a thread calls its
237:meth:`release` method. :meth:`acquire`/:meth:`release` call pairs may be
238nested; only the final :meth:`release` (the :meth:`release` of the outermost
239pair) resets the lock to unlocked and allows another thread blocked in
240:meth:`acquire` to proceed.
241
242
n243-.. method:: XXX Class.acquire([blocking\ ``= 1``])
n424+.. method:: RLock.acquire([blocking=1])
244
245   Acquire a lock, blocking or non-blocking.
246
247   When invoked without arguments: if this thread already owns the lock, increment
248   the recursion level by one, and return immediately.  Otherwise, if another
249   thread owns the lock, block until the lock is unlocked.  Once the lock is
250   unlocked (not owned by any thread), then grab ownership, set the recursion level
251   to one, and return.  If more than one thread is blocked waiting until the lock
255   When invoked with the *blocking* argument set to true, do the same thing as when
256   called without arguments, and return true.
257
258   When invoked with the *blocking* argument set to false, do not block.  If a call
259   without an argument would block, return false immediately; otherwise, do the
260   same thing as when called without arguments, and return true.
261
262
n263-.. method:: XXX Class.release()
n444+.. method:: RLock.release()
264
265   Release a lock, decrementing the recursion level.  If after the decrement it is
266   zero, reset the lock to unlocked (not owned by any thread), and if any other
267   threads are blocked waiting for the lock to become unlocked, allow exactly one
268   of them to proceed.  If after the decrement the recursion level is still
269   nonzero, the lock remains locked and owned by the calling thread.
270
n271-   Only call this method when the calling thread owns the lock. Do not call this
n452+   Only call this method when the calling thread owns the lock. A
272-   method when the lock is unlocked.
453+   :exc:`RuntimeError` is raised if this method is called when the lock is
454+   unlocked.
273
274   There is no return value.
275
276
277.. _condition-objects:
278
279Condition Objects
280-----------------
281
282A condition variable is always associated with some kind of lock; this can be
283passed in or one will be created by default.  (Passing one in is useful when
284several condition variables must share the same lock.)
285
286A condition variable has :meth:`acquire` and :meth:`release` methods that call
287the corresponding methods of the associated lock. It also has a :meth:`wait`
288method, and :meth:`notify` and :meth:`notifyAll` methods.  These three must only
n289-be called when the calling thread has acquired the lock.
n471+be called when the calling thread has acquired the lock, otherwise a
472+:exc:`RuntimeError` is raised.
290
291The :meth:`wait` method releases the lock, and then blocks until it is awakened
292by a :meth:`notify` or :meth:`notifyAll` call for the same condition variable in
293another thread.  Once awakened, it re-acquires the lock and returns.  It is also
294possible to specify a timeout.
295
296The :meth:`notify` method wakes up one of the threads waiting for the condition
297variable, if any are waiting.  The :meth:`notifyAll` method wakes up all threads
345.. method:: Condition.release()
346
347   Release the underlying lock. This method calls the corresponding method on the
348   underlying lock; there is no return value.
349
350
351.. method:: Condition.wait([timeout])
352
n353-   Wait until notified or until a timeout occurs. This must only be called when the
n536+   Wait until notified or until a timeout occurs. If the calling thread has not
354-   calling thread has acquired the lock.
537+   acquired the lock when this method is called, a :exc:`RuntimeError` is raised.
355
356   This method releases the underlying lock, and then blocks until it is awakened
357   by a :meth:`notify` or :meth:`notifyAll` call for the same condition variable in
358   another thread, or until the optional timeout occurs.  Once awakened or timed
359   out, it re-acquires the lock and returns.
360
361   When the *timeout* argument is present and not ``None``, it should be a floating
362   point number specifying a timeout for the operation in seconds (or fractions
367   acquired multiple times recursively.  Instead, an internal interface of the
368   :class:`RLock` class is used, which really unlocks it even when it has been
369   recursively acquired several times. Another internal interface is then used to
370   restore the recursion level when the lock is reacquired.
371
372
373.. method:: Condition.notify()
374
n375-   Wake up a thread waiting on this condition, if any. This must only be called
n558+   Wake up a thread waiting on this condition, if any. Waiuntil notified or until
376-   when the calling thread has acquired the lock.
559+   a timeout occurs. If the calling thread has not acquired the lock when this
560+   method is called, a :exc:`RuntimeError` is raised.
377
378   This method wakes up one of the threads waiting for the condition variable, if
379   any are waiting; it is a no-op if no threads are waiting.
380
381   The current implementation wakes up exactly one thread, if any are waiting.
382   However, it's not safe to rely on this behavior.  A future, optimized
383   implementation may occasionally wake up more than one thread.
384
385   Note: the awakened thread does not actually return from its :meth:`wait` call
386   until it can reacquire the lock.  Since :meth:`notify` does not release the
387   lock, its caller should.
388
389
n390-.. method:: Condition.notifyAll()
n574+.. method:: Condition.notify_all()
575+            Condition.notifyAll()
391
392   Wake up all threads waiting on this condition.  This method acts like
n393-   :meth:`notify`, but wakes up all waiting threads instead of one.
n578+   :meth:`notify`, but wakes up all waiting threads instead of one. If the calling
579+   thread has not acquired the lock when this method is called, a
580+   :exc:`RuntimeError` is raised.
394
395
396.. _semaphore-objects:
397
398Semaphore Objects
399-----------------
400
401This is one of the oldest synchronization primitives in the history of computer
405A semaphore manages an internal counter which is decremented by each
406:meth:`acquire` call and incremented by each :meth:`release` call.  The counter
407can never go below zero; when :meth:`acquire` finds that it is zero, it blocks,
408waiting until some other thread calls :meth:`release`.
409
410
411.. class:: Semaphore([value])
412
n413-   The optional argument gives the initial value for the internal counter; it
n600+   The optional argument gives the initial *value* for the internal counter; it
414-   defaults to ``1``.
601+   defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is
602+   raised.
415
416
417.. method:: Semaphore.acquire([blocking])
418
419   Acquire a semaphore.
420
421   When invoked without arguments: if the internal counter is larger than zero on
422   entry, decrement it by one and return immediately.  If it is zero on entry,
482:meth:`wait` method blocks until the flag is true.
483
484
485.. class:: Event()
486
487   The internal flag is initially false.
488
489
n490-.. method:: Event.isSet()
n678+.. method:: Event.is_set()
679+            Event.isSet()
491
492   Return true if and only if the internal flag is true.
493
494
495.. method:: Event.set()
496
497   Set the internal flag to true. All threads waiting for it to become true are
498   awakened. Threads that call :meth:`wait` once the flag is true will not block at
509
510   Block until the internal flag is true. If the internal flag is true on entry,
511   return immediately.  Otherwise, block until another thread calls :meth:`set` to
512   set the flag to true, or until the optional timeout occurs.
513
514   When the timeout argument is present and not ``None``, it should be a floating
515   point number specifying a timeout for the operation in seconds (or fractions
516   thereof).
n517- 
518- 
519-.. _thread-objects:
520- 
521-Thread Objects
522---------------
523- 
524-This class represents an activity that is run in a separate thread of control.
525-There are two ways to specify the activity: by passing a callable object to the
526-constructor, or by overriding the :meth:`run` method in a subclass.  No other
527-methods (except for the constructor) should be overridden in a subclass.  In
528-other words,  *only*  override the :meth:`__init__` and :meth:`run` methods of
529-this class.
530- 
531-Once a thread object is created, its activity must be started by calling the
532-thread's :meth:`start` method.  This invokes the :meth:`run` method in a
533-separate thread of control.
534- 
535-Once the thread's activity is started, the thread is considered 'alive' and
536-'active' (these concepts are almost, but not quite exactly, the same; their
537-definition is intentionally somewhat vague).  It stops being alive and active
538-when its :meth:`run` method terminates -- either normally, or by raising an
539-unhandled exception.  The :meth:`isAlive` method tests whether the thread is
540-alive.
541- 
542-Other threads can call a thread's :meth:`join` method.  This blocks the calling
543-thread until the thread whose :meth:`join` method is called is terminated.
544- 
545-A thread has a name.  The name can be passed to the constructor, set with the
546-:meth:`setName` method, and retrieved with the :meth:`getName` method.
547- 
548-A thread can be flagged as a "daemon thread".  The significance of this flag is
549-that the entire Python program exits when only daemon threads are left.  The
550-initial value is inherited from the creating thread.  The flag can be set with
551-the :meth:`setDaemon` method and retrieved with the :meth:`isDaemon` method.
552- 
553-There is a "main thread" object; this corresponds to the initial thread of
554-control in the Python program.  It is not a daemon thread.
555- 
556-There is the possibility that "dummy thread objects" are created.  These are
557-thread objects corresponding to "alien threads".  These are threads of control
558-started outside the threading module, such as directly from C code.  Dummy
559-thread objects have limited functionality; they are always considered alive,
560-active, and daemonic, and cannot be :meth:`join`\ ed.  They are never  deleted,
561-since it is impossible to detect the termination of alien threads.
562- 
563- 
564-.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={})
565- 
566-   This constructor should always be called with keyword arguments.  Arguments are:
567- 
568-   *group* should be ``None``; reserved for future extension when a
569-   :class:`ThreadGroup` class is implemented.
570- 
571-   *target* is the callable object to be invoked by the :meth:`run` method.
572-   Defaults to ``None``, meaning nothing is called.
573- 
574-   *name* is the thread name.  By default, a unique name is constructed of the form
575-   "Thread-*N*" where *N* is a small decimal number.
576- 
577-   *args* is the argument tuple for the target invocation.  Defaults to ``()``.
578- 
579-   *kwargs* is a dictionary of keyword arguments for the target invocation.
580-   Defaults to ``{}``.
581- 
582-   If the subclass overrides the constructor, it must make sure to invoke the base
583-   class constructor (``Thread.__init__()``) before doing anything else to the
584-   thread.
585- 
586- 
587-.. method:: Thread.start()
588- 
589-   Start the thread's activity.
590- 
591-   This must be called at most once per thread object.  It arranges for the
592-   object's :meth:`run` method to be invoked in a separate thread of control.
593- 
594- 
595-.. method:: Thread.run()
596- 
597-   Method representing the thread's activity.
598- 
599-   You may override this method in a subclass.  The standard :meth:`run` method
600-   invokes the callable object passed to the object's constructor as the *target*
601-   argument, if any, with sequential and keyword arguments taken from the *args*
602-   and *kwargs* arguments, respectively.
603- 
604- 
605-.. method:: Thread.join([timeout])
606- 
607-   Wait until the thread terminates. This blocks the calling thread until the
608-   thread whose :meth:`join` method is called terminates -- either normally or
609-   through an unhandled exception -- or until the optional timeout occurs.
610- 
611-   When the *timeout* argument is present and not ``None``, it should be a floating
612-   point number specifying a timeout for the operation in seconds (or fractions
613-   thereof). As :meth:`join` always  returns ``None``, you must call
614-   :meth:`isAlive` to decide whether  a timeout happened.
615- 
616-   When the *timeout* argument is not present or ``None``, the operation will block
617-   until the thread terminates.
618- 
619-   A thread can be :meth:`join`\ ed many times.
620- 
621-   A thread cannot join itself because this would cause a deadlock.
622- 
623-   It is an error to attempt to :meth:`join` a thread before it has been started.
624- 
625- 
626-.. method:: Thread.getName()
627- 
628-   Return the thread's name.
629- 
630- 
631-.. method:: Thread.setName(name)
632- 
633-   Set the thread's name.
634- 
635-   The name is a string used for identification purposes only. It has no semantics.
636-   Multiple threads may be given the same name.  The initial name is set by the
637-   constructor.
638- 
639- 
640-.. method:: Thread.isAlive()
641- 
642-   Return whether the thread is alive.
643- 
644-   Roughly, a thread is alive from the moment the :meth:`start` method returns
645-   until its :meth:`run` method terminates.
646- 
647- 
648-.. method:: Thread.isDaemon()
649- 
650-   Return the thread's daemon flag.
651- 
652- 
653-.. method:: Thread.setDaemon(daemonic)
654- 
655-   Set the thread's daemon flag to the Boolean value *daemonic*. This must be
656-   called before :meth:`start` is called.
657- 
658-   The initial value is inherited from the creating thread.
659- 
660-   The entire Python program exits when no active non-daemon threads are left.
661
662
663.. _timer-objects:
664
665Timer Objects
666-------------
667
668This class represents an action that should be run only after a certain amount
704:meth:`release` methods can be used as context managers for a :keyword:`with`
705statement.  The :meth:`acquire` method will be called when the block is entered,
706and :meth:`release` will be called when the block is exited.
707
708Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`,
709:class:`Semaphore`, and :class:`BoundedSemaphore` objects may be used as
710:keyword:`with` statement context managers.  For example::
711
n712-   from __future__ import with_statement
713   import threading
714
715   some_rlock = threading.RLock()
716
717   with some_rlock:
718       print "some_rlock is locked while this executes"
719
t764+ 
765+.. _threaded-imports:
766+ 
767+Importing in threaded code
768+--------------------------
769+ 
770+While the import machinery is thread safe, there are two key
771+restrictions on threaded imports due to inherent limitations in the way
772+that thread safety is provided:
773+ 
774+* Firstly, other than in the main module, an import should not have the
775+  side effect of spawning a new thread and then waiting for that thread in
776+  any way. Failing to abide by this restriction can lead to a deadlock if
777+  the spawned thread directly or indirectly attempts to import a module.
778+* Secondly, all import attempts must be completed before the interpreter
779+  starts shutting itself down. This can be most easily achieved by only
780+  performing imports from non-daemon threads created through the threading
781+  module. Daemon threads and threads created directly with the thread
782+  module will require some other form of synchronization to ensure they do
783+  not attempt imports after system shutdown has commenced. Failure to
784+  abide by this restriction will lead to intermittent exceptions and
785+  crashes during interpreter shutdown (as the late imports attempt to
786+  access machinery which is no longer in a valid state).
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op