Enhance docs a bit re #520 and related hang issues.

2 files changed, 16 insertions, 0 deletions

diff --git a/paramiko/client.py b/paramiko/client.py
index e3d3780e..ebf21b08 100644
--- a/paramiko/client.py
+++ b/paramiko/client.py
@@ -382,6 +382,12 @@ class SSHClient (ClosingContextManager):
     def close(self):
         """
         Close this SSHClient and its underlying `.Transport`.
+
+        .. warning::
+            Failure to do this may, in some situations, cause your Python
+            interpreter to hang at shutdown (often due to race conditions).
+            It's good practice to `close` your client objects anytime you're
+            done using them, instead of relying on garbage collection.
         """
         if self._transport is None:
             return
diff --git a/sites/www/faq.rst b/sites/www/faq.rst
index a5d9b383..74b7501e 100644
--- a/sites/www/faq.rst
+++ b/sites/www/faq.rst
@@ -24,3 +24,13 @@ However, **closed does not imply locked** - affected users can still post
 comments on such tickets - and **we will always consider actual patch
 submissions for these issues**, provided they can get +1s from similarly
 affected users and are proven to not break existing functionality.
+
+I'm having strange issues with my code hanging at shutdown!
+===========================================================
+
+Make sure you explicitly ``.close()`` your connection objects (usually
+``SSHClient``) if you're having any sort of hang/freeze at shutdown time!
+
+Doing so isn't strictly necessary 100% of the time, but it is almost always the
+right solution if you run into the various corner cases that cause race
+conditions, etc.