docs: Update for the fork and server modules

docs/aiotools.fork.rst

@@ -0,0 +1,14 @@
+Async Fork
+==========
+
+.. automodule:: aiotools.fork
+
+.. currentmodule:: aiotools.fork
+
+.. autoclass:: aiotools.fork.AbstractChildProcess
+
+.. autofunction:: aiotools.fork.PosixChildProcess
+
+.. autofunction:: aiotools.fork.PidfdChildProcess
+
+.. autofunction:: aiotools.fork.afork

docs/index.rst

@@ -13,6 +13,7 @@ aiotools Documentation
 
    aiotools.context
    aiotools.defer
+   aiotools.fork
    aiotools.func
    aiotools.iter
    aiotools.server

src/aiotools/fork.py

@@ -2,6 +2,10 @@
 This module implements a simple :func:`os.fork()`-like interface,
 but in an asynchronous way with full support for PID file descriptors
 on Python 3.9 or higher and the Linux kernel 5.4 or higher.
+
+It internally synchronizes the beginning and readiness status of child processes
+so that the users may assume that the child process is completely interruptible after
+:func:`afork()` returns.
 """
 
 import asyncio
@@ -50,6 +54,9 @@
 
 
 class AbstractChildProcess(metaclass=ABCMeta):
+    """
+    The abstract interface to control and monitor a forked child process.
+    """
 
     @abstractmethod
     def send_signal(self, signum: int) -> None:
@@ -61,6 +68,9 @@ async def wait(self) -> int:
 
 
 class PosixChildProcess(AbstractChildProcess):
+    """
+    A POSIX-compatible version of :class:`AbstractChildProcess`.
+    """
 
     def __init__(self, pid: int) -> None:
         self._pid = pid
@@ -102,6 +112,9 @@ async def wait(self) -> int:
 
 
 class PidfdChildProcess(AbstractChildProcess):
+    """
+    A PID file descriptor-based version of :class:`AbstractChildProcess`.
+    """
 
     def __init__(self, pid: int, pidfd: int) -> None:
         self._pid = pid
@@ -238,6 +251,11 @@ async def _clone_pidfd(child_func: Callable[[], int]) -> Tuple[int, int]:
 
 
 async def afork(child_func: Callable[[], int]) -> AbstractChildProcess:
+    """
+    Fork the current process and execute the given function in the child.
+    The return value of the function will become the exit code of the child
+    process.
+    """
     if _has_pidfd:
         pid, pidfd = await _clone_pidfd(child_func)
         return PidfdChildProcess(pid, pidfd)

src/aiotools/server.py

@@ -416,27 +416,11 @@ def start_server(
 
         extra_procs: An iterable of functions that consist of extra processes
                      whose lifecycles are synchronized with other workers.
-
-                     You should write the shutdown steps of them differently
-                     depending on the value of **use_threading** argument.
-
-                     If it is ``False`` (default), they will get
-                     a :class:`BaseException` depending on the received stop signal
-                     number, either :class:`KeyboardInterrupt` (for SIGINT),
-                     :class:`SystemExit` (for SIGTERM), or
-                     :class:`InterruptedBySignal` (otherwise).
-
-                     If it is ``True``, they should check their **intr_event**
-                     argument periodically because there is no way to install
-                     signal handlers in Python threads (only the main thread
-                     can install signal handlers).
+                     They should set up their own signal handlers.
 
                      It should accept the following three arguments:
 
-                     * **intr_event**: :class:`threading.Event` object that
-                       signals the interruption of the main thread (only
-                       available when **use_threading** is ``True``; otherwise
-                       it is set to ``None``)
+                     * **intr_event**: Always ``None``, kept for legacy
                      * **pidx**: same to **worker_actxmgr** argument
                      * **args**: same to **worker_actxmgr** argument
 
@@ -490,11 +474,16 @@ def start_server(
        **start_method** argument can be set to change the subprocess spawning
        implementation.
 
-    .. versionchanged:: 1.2.0
+    .. deprecated:: 1.2.0
 
-       Deprecated **start_method** and **use_threading**, in favor of our new
+       The **start_method** and **use_threading** arguments, in favor of our new
        :func:`afork()` function which provides better synchronization and pid-fd
        support.
+
+    .. versionchanged:: 1.2.0
+
+       The **extra_procs** will be always separate processes since **use_threading**
+       is deprecated and thus **intr_event** arguments are now always ``None``.
     """
 
     @_main_ctxmgr