From f6743d3ccbc087f54dc6fce39e65c42fc396abfb Mon Sep 17 00:00:00 2001
From: Arnaud <arnaud@status.im>
Date: Thu, 11 Sep 2025 14:55:44 +0200
Subject: [PATCH] Add limitation doc

---
 README.md                                              | 4 ++++
 library/codex_thread_requests/codex_thread_request.nim | 6 ++++++
 2 files changed, 10 insertions(+)

diff --git a/README.md b/README.md
index 4249c347..97139bee 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,10 @@ Run the example:
 By default, Codex builds a dynamic library (`libcodex.so`), which you can load at runtime.
 If you prefer a static library (`libcodex.a`), set the `STATIC` flag:
 
+### Limitation
+
+Callbacks must be fast and non-blocking; otherwise, the working thread will hang and prevent other requests from being processed.
+
 ```bash
 # Build dynamic (default)
 make libcodex
diff --git a/library/codex_thread_requests/codex_thread_request.nim b/library/codex_thread_requests/codex_thread_request.nim
index 00acc526..88d0a678 100644
--- a/library/codex_thread_requests/codex_thread_request.nim
+++ b/library/codex_thread_requests/codex_thread_request.nim
@@ -40,6 +40,12 @@ proc createShared*(
   ret[].userData = userData
   return ret
 
+# NOTE: User callbacks are executed on the working thread.
+# They must be fast and non-blocking; otherwise this thread will be blocked
+# and no further requests can be processed.
+# We can improve this by dispatching the callbacks to a thread pool or
+# moving to a MP channel.
+# See: https://github.com/codex-storage/nim-codex/pull/1322#discussion_r2340708316
 proc handleRes[T: string | void](
     res: Result[T, string], request: ptr CodexThreadRequest
 ) =