From df27a1bacc792867587a8b89ee3702f02fe5b5a0 Mon Sep 17 00:00:00 2001
From: Edmond <1571649+EdmondDantes@users.noreply.github.com>
Date: Tue, 25 Aug 2026 16:18:27 +0300
Subject: [PATCH] docs(async): state what ZEND_ASYNC_IO_PRESERVE_FD reaches

---
 Zend/zend_async_API.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Zend/zend_async_API.h b/Zend/zend_async_API.h
index a515b5b45ec8..ac53f35156e8 100644
--- a/Zend/zend_async_API.h
+++ b/Zend/zend_async_API.h
@@ -120,6 +120,12 @@ typedef enum {
 #define ZEND_ASYNC_IO_CLOSED      (1 << 2)
 #define ZEND_ASYNC_IO_EOF         (1 << 3)
 #define ZEND_ASYNC_IO_APPEND      (1 << 4)
+/* Keep the descriptor when the io is disposed. It reaches only a descriptor the
+ * reactor closes on its own account — a file, or a copy the reactor made — so a
+ * descriptor a stream handle adopts is outside it: the backend owns such a
+ * handle and closes what it adopted, this flag or not. A caller that must keep
+ * a socket alive past the io therefore cannot; it hands the socket over, or
+ * hands over a copy of its own and lives with two file descriptions. */
 #define ZEND_ASYNC_IO_PRESERVE_FD (1 << 5)
 #define ZEND_ASYNC_IO_OWNS_FD     (1 << 6) /* reactor owns crt_fd and must close it on dispose */
 /* A write on this handle completed with an error. The reactor sets it and