#1720705: add docs about import/threading interaction, wording by Nick.

diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 077ae0119c29d927134e9b72d34d3353fbf426e0..8cb84b3c8c681ed05aa97c6ee72eb9d3940a82f3 100644 (file)
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -731,3 +731,26 @@ Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`,
    with some_rlock:
        print "some_rlock is locked while this executes"
 
+
+.. _threaded-imports:
+
+Importing in threaded code
+--------------------------
+
+While the import machinery is thread safe, there are two key
+restrictions on threaded imports due to inherent limitations in the way
+that thread safety is provided:
+
+* Firstly, other than in the main module, an import should not have the
+  side effect of spawning a new thread and then waiting for that thread in
+  any way. Failing to abide by this restriction can lead to a deadlock if
+  the spawned thread directly or indirectly attempts to import a module.
+* Secondly, all import attempts must be completed before the interpreter
+  starts shutting itself down. This can be most easily achieved by only
+  performing imports from non-daemon threads created through the threading
+  module. Daemon threads and threads created directly with the thread
+  module will require some other form of synchronization to ensure they do
+  not attempt imports after system shutdown has commenced. Failure to
+  abide by this restriction will lead to intermittent exceptions and
+  crashes during interpreter shutdown (as the late imports attempt to
+  access machinery which is no longer in a valid state).