migrazione verso gitea

async_loop_singleton.py

@@ -1,16 +1,31 @@
-# async_loop_singleton.py
-import asyncio, threading
-from typing import Callable
+"""Shared asyncio loop lifecycle helpers for the desktop application.
+
+The GUI runs on Tk's main thread, while database calls are executed on a
+dedicated background event loop. These helpers expose that loop as a lazy
+singleton so every module can schedule work on the same async runtime.
+"""
+
+import asyncio
+import threading
+
 
 class _LoopHolder:
+    """Store the global loop instance and its worker thread."""
+
     def __init__(self):
         self.loop = None
         self.thread = None
 
+
 _GLOBAL = _LoopHolder()
 
+
 def get_global_loop() -> asyncio.AbstractEventLoop:
-    """Start a single asyncio loop in a background thread and return it."""
+    """Return the shared background event loop.
+
+    The loop is created lazily the first time the function is called and kept
+    alive for the lifetime of the application.
+    """
     if _GLOBAL.loop:
         return _GLOBAL.loop
 
@@ -27,7 +42,9 @@ def get_global_loop() -> asyncio.AbstractEventLoop:
     ready.wait()
     return _GLOBAL.loop
 
+
 def stop_global_loop():
+    """Stop the shared loop and join the background thread if present."""
     if _GLOBAL.loop and _GLOBAL.loop.is_running():
         _GLOBAL.loop.call_soon_threadsafe(_GLOBAL.loop.stop)
         _GLOBAL.thread.join(timeout=2)