Doc nits for bpo-16500

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
 ==========

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.
  */