docs: add asyncio vs. threading

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/threading.rst

@@ -1,54 +1,72 @@
 .. _threading:
 
-Using library in threaded environments
-======================================
+Using the library in threaded environments
+==========================================
 
 Network namespaces
 ------------------
 
-In order to run a separate socket in network namespace `A` while keeping
-the Python process in namespace `B`, the library performs these steps:
+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 using `socket.send_fds()` back to the parent
-5. terminate the child process
-6. create a socket with `socket(fileno=...)`
+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, in the parent process we get a socket that belongs to another
-network namespace, but we can use it natively like any other socket, both in
-sync and async way.
+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.
 
-Start a child: os.fork()
-------------------------
+Starting a child process: os.fork()
+-----------------------------------
 
-By default, pyroute2 uses `os.fork()` to create the child. When using it
-in multithreaded processes, no threads will be recreated, and the child
-will only continue the thread where `os.fork()` was called in. This leaves
-the GC in a corrupted state.
+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.
 
-This should not be an issue since the socket creation routine stops the GC,
-and doesn't rely on any shared data. But still there is some risk.
+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.
 
-That's why pyroute2 provides a configuration option
-`config.child_process_mode`. By default it is `"fork"`, but you can change
-the option to `"mp"`, and then pyroute2 will use `multiprocessing` to
-create and control the child process.
+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.
 
-Start a child: multiprocessing
-------------------------------
+Starting a child process: multiprocessing
+-----------------------------------------
 
-Using `multiprocessing` may or may not rely on `os.fork()`, it depends on
-`multiprocessing.set_start_method()`. In Python version < 3.14 the default
-is `"fork"`, but starting with 3.14, the default is `"spawn"`.
+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. Beside of that, `"spawn"`
-implies additional limitations by pickling the target method and its
-arguments. This prevents passing lambdas as the target, and make impossible
-to pass the `libc` instance to the child process.
+Using `"spawn"` is safer but significantly slower. Additionally, `"spawn"`
+introduces limitations due to pickling:
 
-The `multiprocessing` start method is out of scope for pyroute2, thus no
-way to set it using `config.child_process_mode`, where you can specify
-only `"mp"`. You have to run `multiprocessing.set_start_method()` by
-yourself somewhere else in your program then.
+* 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()`.