docs: Merge pull request #1324 from svinota/p11-docs-threading

docs: add threading vs. fork documentation

Bug-Url: #1324

Author: svinota

docs/asyncio.rst

@@ -184,24 +184,3 @@ such as `GenericNetlinkSocket`, or using custom wrappers, like in
 `IPRoute`. The plan is to refactor all components to provide an asynchronous
 API, keeping the synchronous API for compatibility with existing projects
 that use pyroute2.
-
-Thread safety
--------------
-
-Is the current core thread-safe? Yes and no at the same time. While there
-are no locks in the core, components like sockets and message queues are 
-now thread-local.
-
-This means that the same pyroute2 socket object manages as many
-underlying netlink sockets as there are threads accessing it.
-
-Pros:
-
-* Simplicity and absence of mutexes, which eliminates the risk of deadlocks.
-
-Cons:
-
-* Race conditions are still possible if shared data is not thread-local.
-* Debugging existing netlink flows at runtime is limited because any
-  debugger session will create its own underlying netlink socket. This
-  makes logging and post-mortem analysis more important.

docs/index.rst

@@ -21,6 +21,7 @@ Usage
 
     usage
     asyncio
+    threading
     iproute
     ndb
     fixtures

docs/threading.rst

@@ -0,0 +1,72 @@
+.. _threading:
+
+Using the library in threaded environments
+==========================================
+
+Network namespaces
+------------------
+
+To run a separate socket in one network namespace while keeping the
+Python process in another namespace, the library follows these steps:
+
+1. Spawn a child process.
+2. Execute `netns.setns()` in the child.
+3. Create a socket.
+4. Send the file descriptor back to the parent using `socket.send_fds()`.
+5. Terminate the child process.
+6. Create a socket in the parent using `socket(fileno=...)`.
+
+As a result, the parent process obtains a socket belonging to
+another network namespace. However, it can be used natively like
+any other socket, both synchronously and asynchronously.
+
+Starting a child process: os.fork()
+-----------------------------------
+
+By default, pyroute2 uses `os.fork()` to create the child process.
+In multithreaded environments, `os.fork()` does not recreate threads;
+the child process continues only from the thread where `os.fork()`
+was called. This can leave the garbage collector in a corrupted state.
+
+While this is generally not an issue -- since the socket creation routine
+stops the garbage collector, and does not rely on shared data -- there
+is still some risk.
+
+To address this, pyroute2 provides a configuration option:
+`config.child_process_mode`. The default value is `"fork"`, but you
+can change it to `"mp"` to use the `multiprocessing` module for creating
+and managing the child process.
+
+Starting a child process: multiprocessing
+-----------------------------------------
+
+The `multiprocessing` module may or may not rely on `os.fork()`, depending
+on the method set via `multiprocessing.set_start_method()`. In Python
+versions earlier than 3.14, the default method is `"fork"`, but starting
+from Python 3.14, the default is `"spawn"`.
+
+Using `"spawn"` is safer but significantly slower. Additionally, `"spawn"`
+introduces limitations due to pickling:
+
+* The target function and its arguments must be pickleable.
+* Passing lambda functions as the target is not possible.
+* The libc instance cannot be passed to the child process.
+
+Since pyroute2 does not manage the `multiprocessing` start method, the
+start method cannot be configured via `config.child_process_mode`. If you
+set `config.child_process_mode` to `"mp"`, and need to explicitly specify
+the start method, you must call `multiprocessing.set_start_method()`
+manually elsewhere in your program.
+
+Threading and asyncio
+---------------------
+
+An asyncio event loop can only run in the thread where it was started.
+In a multithreaded environment, the library creates a local event loop
+and a local netlink socket for each thread that accesses the object.
+While this approach is safe, it complicates object termination.
+Although an event loop can be stopped from another thread, it cannot
+be closed.
+
+The best solution is to call `close()` in every thread where you
+call `bind()`.