From 28a7d204ad6e8bfa503f9f8afe2b8f23cb16238e Mon Sep 17 00:00:00 2001
From: SomberNight <somber.night@protonmail.com>
Date: Thu, 11 Mar 2021 18:50:59 +0100
Subject: [PATCH] util: document CallbackManager behaviour

---
 electrum/util.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/electrum/util.py b/electrum/util.py
index 0e2b0f4db..cc5d38ed6 100644
--- a/electrum/util.py
+++ b/electrum/util.py
@@ -1380,7 +1380,9 @@ def randrange(bound: int) -> int:
 
 
 class CallbackManager:
-        # callbacks set by the GUI
+    # callbacks set by the GUI or any thread
+    # guarantee: the callbacks will always get triggered from the asyncio thread.
+
     def __init__(self):
         self.callback_lock = threading.Lock()
         self.callbacks = defaultdict(list)      # note: needs self.callback_lock
@@ -1398,6 +1400,10 @@ class CallbackManager:
                     callbacks.remove(callback)
 
     def trigger_callback(self, event, *args):
+        """Trigger a callback with given arguments.
+        Can be called from any thread. The callback itself will get scheduled
+        on the event loop.
+        """
         if self.asyncio_loop is None:
             self.asyncio_loop = asyncio.get_event_loop()
             assert self.asyncio_loop.is_running(), "event loop not running"