docs: add comments explaining internal request handling

src/fs-poll.c

@@ -175,7 +175,9 @@ static void timer_cb(uv_timer_t *timer) {
   if (uv_fs_stat(ctx->loop, &ctx->fs_req, ctx->path, poll_cb))
     abort();
 
-  /* Mark fs_req as internal and unregister it. */
+  /* Mark fs_req as internal so it doesn't keep the loop alive.
+   * We also unregister it immediately because uv_fs_stat registers it.
+   */
   ctx->fs_req.reserved[0] = UV__REQ_INTERNAL;
   uv__req_unregister(ctx->loop);
 }

src/unix/fs.c

@@ -1647,6 +1647,10 @@ static void uv__fs_done(struct uv__work *w, int status) {
 
   req = container_of(w, uv_fs_t, work_req);
 
+  /* Internal requests are not registered with the loop, so we shouldn't
+   * unregister them. Unregistering would decrement the active request
+   * count incorrectly.
+   */
   if (req->reserved[0] != UV__REQ_INTERNAL)
     uv__req_unregister(req->loop);
 

src/uv-common.h

@@ -33,10 +33,10 @@
 #include <stdint.h>
 #include <string.h>
 
-#include "uv.h"
-#include "uv/tree.h"
 #include "queue.h"
 #include "strscpy.h"
+#include "uv.h"
+#include "uv/tree.h"
 
 #ifndef _MSC_VER
 #include <stdatomic.h>
@@ -141,6 +141,10 @@ enum {
   UV_HANDLE_REAP = 0x10000000
 };
 
+/* Internal requests (like those used by uv_fs_poll) are marked with this
+ * flag to prevent them from being counted in the active request count.
+ * This avoids keeping the loop alive unnecessarily.
+ */
 #define UV__REQ_INTERNAL ((void *)(uintptr_t)0x8000)
 
 static inline int uv__is_raw_tty_mode(uv_tty_mode_t m) {

src/win/fs.c

@@ -2968,6 +2968,10 @@ static void uv__fs_done(struct uv__work *w, int status) {
 
   req = container_of(w, uv_fs_t, work_req);
 
+  /* Internal requests are not registered with the loop, so we shouldn't
+   * unregister them. Unregistering would decrement the active request
+   * count incorrectly.
+   */
   if (req->reserved[0] != UV__REQ_INTERNAL)
     uv__req_unregister(req->loop);