Merged revisions 74841 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74841 | thomas.wouters | 2009-09-16 12:55:54 -0700 (Wed, 16 Sep 2009) | 23 lines


  Fix issue #1590864, multiple threads and fork() can cause deadlocks, by
  acquiring the import lock around fork() calls. This prevents other threads
  from having that lock while the fork happens, and is the recommended way of
  dealing with such issues. There are two other locks we care about, the GIL
  and the Thread Local Storage lock. The GIL is obviously held when calling
  Python functions like os.fork(), and the TLS lock is explicitly reallocated
  instead, while also deleting now-orphaned TLS data.

  This only fixes calls to os.fork(), not extension modules or embedding
  programs calling C's fork() directly. Solving that requires a new set of API
  functions, and possibly a rewrite of the Python/thread_*.c mess. Add a
  warning explaining the problem to the documentation in the mean time.

  This also changes behaviour a little on AIX. Before, AIX (but only AIX) was
  getting the import lock reallocated, seemingly to avoid this very same
  problem. This is not the right approach, because the import lock is a
  re-entrant one, and reallocating would do the wrong thing when forking while
  holding the import lock.

  Will backport to 2.6, minus the tiny AIX behaviour change.
........

1 files changed, 16 insertions, 0 deletions

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 7beb211..ae93a36 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -523,6 +523,22 @@ supports the creation of additional interpreters (using
 :cfunc:`Py_NewInterpreter`), but mixing multiple interpreters and the
 :cfunc:`PyGILState_\*` API is unsupported.
 
+Another important thing to note about threads is their behaviour in the face
+of the C :cfunc:`fork` call. On most systems with :cfunc:`fork`, after a
+process forks only the thread that issued the fork will exist. That also
+means any locks held by other threads will never be released. Python solves
+this for :func:`os.fork` by acquiring the locks it uses internally before
+the fork, and releasing them afterwards. In addition, it resets any
+:ref:`lock-objects` in the child. When extending or embedding Python, there
+is no way to inform Python of additional (non-Python) locks that need to be
+acquired before or reset after a fork. OS facilities such as
+:cfunc:`posix_atfork` would need to be used to accomplish the same thing.
+Additionally, when extending or embedding Python, calling :cfunc:`fork`
+directly rather than through :func:`os.fork` (and returning to or calling
+into Python) may result in a deadlock by one of Python's internal locks
+being held by a thread that is defunct after the fork.
+:cfunc:`PyOS_AfterFork` tries to reset the necessary locks, but is not
+always able to.
 
 .. ctype:: PyInterpreterState