From aefd087390f42f485abb0a067c0f43ceeebebff1 Mon Sep 17 00:00:00 2001
From: shum <github.shum@liber.li>
Date: Thu, 15 Oct 2026 06:57:21 +0000
Subject: [PATCH] smp-server: clarify command slot comments

---
 src/Simplex/Messaging/Server.hs | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/Simplex/Messaging/Server.hs b/src/Simplex/Messaging/Server.hs
index c2da6f586..cda83237d 100644
--- a/src/Simplex/Messaging/Server.hs
+++ b/src/Simplex/Messaging/Server.hs
@@ -1513,7 +1513,8 @@ client
     -- Run a slow command on a thread that sends its response
     forkCmd_ :: (ServerConfig s -> Int) -> NetworkRequestMode -> M s () -> M s () -> M s (Maybe a)
     forkCmd_ concurrency nm onTimeout cmd = do
-      -- the forked thread releases the slot when the command completes, the caller only if the fork failed
+      -- Exceptions are masked so the slot is never lost between taking it and starting the thread.
+      -- The thread frees the slot when the command finishes; the caller frees it only if forking failed.
       mask $ \restore ->
         wait >>= \case
           True ->
@@ -1522,7 +1523,9 @@ client
           False -> restore onTimeout
       pure Nothing
       where
-        -- the wait is limited by the client timeout of the command, after which its response is not needed
+        -- Takes a free slot at once if there is one. Otherwise waits for a slot until the client
+        -- timeout, after which the client no longer expects the response.
+        -- Other commands of this client are not processed while it waits.
         wait = do
           limit <- asks (concurrency . config)
           ifM (atomically $ takeSlot limit) (pure True) $ do
@@ -2213,7 +2216,8 @@ client
             Right t''@(_, (corrId', entId', cmd')) -> case cmd' of
               Cmd SResolver (RSLV d) -> lift $ rslvNamesEnv >>= \case
                 Nothing -> pure $ Just (corrId', entId', ERR (NAME NO_RESOLVER))
-                -- no response when the slot wait timed out, as the proxy also times out the forward
+                -- The proxy waits for forwarded commands with the background timeout.
+                -- If no slot is free before it, there is no response, as the proxy has already timed out.
                 Just nenv -> forkCmd_ serverResolverConcurrency NRMBackground (pure ()) $ do
                   msg <- resolveNameMsg (thVersion clntTHParams) nenv d
                   rres <- either ERR id <$> runExceptT (encodeResp (corrId', entId', msg))