Async Fork

This module implements a simple 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 afork() returns.

Changed in version 1.9.0: The internal implementation has changed to use multiprocessing to embrace posix_spawn() in macOS and Windows platforms. This introduces a potential BREAKING CHANGE that users now must pass module-level functions or class methods as the target function of afork(), so that they can be imported in the new subprocess.

class AbstractChildProcess

The abstract interface to control and monitor a forked child process.

abstract property pid: int

The process ID of the child process.

abstractmethod send_signal(signum: int) → None

Send a UNIX signal to the child process. If the child process is already terminated, it will log a warning message and return.

abstractmethod async wait() → int

Wait until the child process terminates or reclaim the child process’ exit code if already terminated. If there are other coroutines that has waited the same process, it may return 255 and log a warning message.

PosixChildProcess(proc: MPProcess, pid: int) → None

A POSIX-compatible version of AbstractChildProcess.

Changed in version 1.9.0: The wait() method now polls the status of child process instead of launching a separate thread that makes a blocking os.waitpid() syscall. The polling interval may be adjusted using the class attribute poll_interval, which defaults to 50 msec.

PidfdChildProcess(proc: MPProcess, pid: int, pidfd: int) → None

A pidfd (PID file descriptor) based version of AbstractChildProcess.

The main advantage of pidfd is that we no longer need to actively poll the child status, making the whole operation async-native.

Note that pidfd may not be available on all Linux systems depending on at which Linux kernel version your Python executable is built.

async afork(child_func: Callable[[], int], *, mp_context: DefaultContext | ForkContext | ForkServerContext | SpawnContext | None = None) → 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.

Parameters:

• child_func – A function that represents the main function of the child and returns an integer as its exit code. Note that the function must set up a new event loop if it wants to run asyncio codes.

• mp_context – The multiprocessing context to use. If not provided, the default context will be used.

Added in version 1.9.0: The argument mp_context.