bpo-16500: Don't use string constants for os.register_at_fork() behavior (#1834)
Instead use keyword only arguments to os.register_at_fork for each of the scenarios.
Updates the documentation for clarity.
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index c6777d6..95d9d65 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -49,9 +49,10 @@
.. c:function:: void PyOS_AfterFork_Child()
- Function to update some internal state after a process fork. This
- should be called from the child process after calling :c:func:`fork`
- or any similar function that clones the current process.
+ Function to update internal interpreter state after a process fork.
+ This must be called from the child process after calling :c:func:`fork`,
+ or any similar function that clones the current process, if there is
+ any chance the process will call back into the Python interpreter.
Only available on systems where :c:func:`fork` is defined.
.. versionadded:: 3.7
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 28921ad..86add0c 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -3280,16 +3280,22 @@
subprocesses.
-.. function:: register_at_fork(func, when)
+.. function:: register_at_fork(*, before=None, after_in_parent=None, \
+ after_in_child=None)
- Register *func* as a function to be executed when a new child process
- is forked. *when* is a string specifying at which point the function is
- called and can take the following values:
+ Register callables to be executed when a new child process is forked
+ using :func:`os.fork` or similar process cloning APIs.
+ The parameters are optional and keyword-only.
+ Each specifies a different call point.
- * *"before"* means the function is called before forking a child process;
- * *"parent"* means the function is called from the parent process after
- forking a child process;
- * *"child"* means the function is called from the child process.
+ * *before* is a function called before forking a child process.
+ * *after_in_parent* is a function called from the parent process
+ after forking a child process.
+ * *after_in_child* is a function called from the child process.
+
+ These calls are only made if control is expected to return to the
+ Python interpreter. A typical :mod:`subprocess` launch will not
+ trigger them as the child is not going to re-enter the interpreter.
Functions registered for execution before forking are called in
reverse registration order. Functions registered for execution
@@ -3300,6 +3306,8 @@
call those functions, unless it explicitly calls :c:func:`PyOS_BeforeFork`,
:c:func:`PyOS_AfterFork_Parent` and :c:func:`PyOS_AfterFork_Child`.
+ There is no way to unregister a function.
+
Availability: Unix.
.. versionadded:: 3.7