Doc nits for bpo-16500 (#1841)

* Doc nits for bpo-16500 * Fix more references

Author: pitrou

Doc/c-api/init.rst

@@ -564,7 +564,7 @@ Additionally, when extending or embedding Python, calling :c:func:`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.
-:c:func:`PyOS_AfterFork` tries to reset the necessary locks, but is not
+:c:func:`PyOS_AfterFork_Child` tries to reset the necessary locks, but is not
 always able to.
 
 
@@ -675,9 +675,9 @@ code, or when embedding the Python interpreter:
 
 .. c:function:: void PyEval_ReInitThreads()
 
- This function is called from :c:func:`PyOS_AfterFork` to ensure that newly
- created child processes don't hold locks referring to threads which
- are not running in the child process.
+ This function is called from :c:func:`PyOS_AfterFork_Child` to ensure
+ that newly created child processes don't hold locks referring to threads
+ which are not running in the child process.
 
 
 The following functions use thread-local storage, and are not compatible

Doc/whatsnew/3.7.rst

@@ -166,6 +166,10 @@ Serhiy Storchaka in :issue:`28682`.)
 Added support for :ref:`file descriptors <path_fd>` in :func:`~os.scandir`
 on Unix. (Contributed by Serhiy Storchaka in :issue:`25996`.)
 
+New function :func:`os.register_at_fork` allows registering Python callbacks
+to be executed on a process fork. (Contributed by Antoine Pitrou in
+:issue:`16500`.)
+
 unittest.mock
 -------------
 
@@ -243,6 +247,11 @@ Build and C API Changes
 * Added functions :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`.
  (Contributed by Serhiy Storchaka in :issue:`27867`.)
 
+* :c:func:`PyOS_AfterFork` is deprecated in favour of the new functions
+ :c:func:`PyOS_BeforeFork`, :c:func:`PyOS_AfterFork_Parent` and
+ :c:func:`PyOS_AfterFork_Child`. (Contributed by Antoine Pitrou in
+ :issue:`16500`.)
+
 
 Deprecated
 ==========

Lib/threading.py

@@ -1320,8 +1320,8 @@ def main_thread():
 
 def _after_fork():
  # This function is called by Python/ceval.c:PyEval_ReInitThreads which
- # is called from PyOS_AfterFork. Here we cleanup threading module state
- # that should not exist after a fork.
+ # is called from PyOS_AfterFork_Child. Here we cleanup threading module
+ # state that should not exist after a fork.
 
  # Reset _active_limbo_lock, in case we forked while the lock was held
  # by another (non-forked) thread. http://bugs.python.org/issue874900

Misc/NEWS

@@ -1052,6 +1052,9 @@ Windows
 C API
 -----
 
+- bpo-16500: Deprecate PyOS_AfterFork() and add PyOS_BeforeFork(),
+ PyOS_AfterFork_Parent() and PyOS_AfterFork_Child().
+
 - bpo-6532: The type of results of PyThread_start_new_thread() and
  PyThread_get_thread_ident(), and the id parameter of
  PyThreadState_SetAsyncExc() changed from "long" to "unsigned long".

Python/ceval.c

@@ -232,10 +232,10 @@ PyEval_ReleaseThread(PyThreadState *tstate)
  drop_gil(tstate);
 }
 
-/* This function is called from PyOS_AfterFork to destroy all threads which are
- * not running in the child process, and clear internal locks which might be
- * held by those threads. (This could also be done using pthread_atfork
- * mechanism, at least for the pthreads implementation.) */
+/* This function is called from PyOS_AfterFork_Child to destroy all threads
+ * which are not running in the child process, and clear internal locks
+ * which might be held by those threads.
+ */
 
 void
 PyEval_ReInitThreads(void)

Python/import.c

@@ -194,7 +194,7 @@ _PyImport_ReleaseLock(void)
  return 1;
 }
 
-/* This function is called from PyOS_AfterFork to ensure that newly
+/* This function is called from PyOS_AfterFork_Child to ensure that newly
  created child processes do not share locks with the parent.
  We now acquire the import lock around fork() calls but on some platforms
  (Solaris 9 and earlier? see isue7242) that still left us with problems. */

Python/pystate.c

@@ -800,7 +800,7 @@ _PyGILState_Fini(void)
  autoInterpreterState = NULL;
 }
 
-/* Reset the TLS key - called by PyOS_AfterFork().
+/* Reset the TLS key - called by PyOS_AfterFork_Child().
  * This should not be necessary, but some - buggy - pthread implementations
  * don't reset TLS upon fork(), see issue #10517.
  */

Python/thread.c

@@ -325,7 +325,7 @@ PyThread_delete_key_value(int key)
 }
 
 /* Forget everything not associated with the current thread id.
- * This function is called from PyOS_AfterFork(). It is necessary
+ * This function is called from PyOS_AfterFork_Child(). It is necessary
  * because other thread ids which were in use at the time of the fork
  * may be reused for new threads created in the forked process.
  */