From b4a43bf2f24e642e9c78a984b8c1aa998ef19c77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Sur=C3=BD?= Date: Thu, 29 Sep 2022 11:12:15 +0200 Subject: [PATCH] Add developer documentation on the netmgr callbacks Extra care must be taken when executing the callbacks to prevent the deadlocks on the caller's side. Add a paragraph that addresses when we can and when we cannot call the callbacks directly. --- doc/dev/loopmgr.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/dev/loopmgr.md b/doc/dev/loopmgr.md index 9c4518154c..15831e6236 100644 --- a/doc/dev/loopmgr.md +++ b/doc/dev/loopmgr.md @@ -104,3 +104,13 @@ functions MUST be called from the thread that created the network manager socket. The ``isc_nm_listen*()`` functions MUST be called from the ``main`` loop. + +The general design of Network Manager is based on callbacks. An extra care must +be taken when implementing new functions because the callbacks MUST be called +asynchronously because the caller might be inside a lock and the same lock must +be acquired in the callback. This doesn't mean that the callback must be always +called asynchronously, because sometimes we are already in the libuv callback +and thus we can just call the callback directly, but in other places, especially +when returning an error, the control hasn't been returned to the caller yet and +in such case, the callback must be scheduled onto the event loop instead of +executing it directly.