From a5e54e662086b5a34c5613ed3ece9240b1b2462f Mon Sep 17 00:00:00 2001
From: Arnaud Le Blanc <arnaud.lb@gmail.com>
Date: Wed, 13 Nov 2024 13:42:08 +0100
Subject: [PATCH] Document changes related to Fibers and destructors

---
 language/fibers.xml     |  4 +++-
 language/oop5/decon.xml | 20 ++++++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/language/fibers.xml b/language/fibers.xml
index 3da63d75d73f..eae91489d4c6 100644
--- a/language/fibers.xml
+++ b/language/fibers.xml
@@ -36,7 +36,9 @@
   </para>
   <note>
    <simpara>
-    Due to current limitations it is not possible to switch fibers in the destructor of an object.
+    Prior to PHP 8.4.0, switching fibers during the execution of an object
+    <link linkend="language.oop5.decon.destructor">destructor</link> was not
+    allowed.
    </simpara>
   </note> 
 
diff --git a/language/oop5/decon.xml b/language/oop5/decon.xml
index ee83e45ebe2b..7032fe6b1261 100644
--- a/language/oop5/decon.xml
+++ b/language/oop5/decon.xml
@@ -343,6 +343,26 @@ $obj = new MyDestructableClass();
     <function>exit</function>. Calling <function>exit</function> in a destructor
     will prevent the remaining shutdown routines from executing.
    </para>
+   <para>
+    If a destructor creates new references to its object, it will not be called
+    a second time when the reference count reaches zero again or during the
+    shutdown sequence.
+   </para>
+   <para>
+    As of PHP 8.4.0, when
+    <link linkend="features.gc.collecting-cycles">cycle collection</link>
+    occurs during the execution of a
+    <link linkend="language.fibers">Fiber</link>, the destructors of objects
+    scheduled for collection are executed in a separate Fiber, called the
+    <literal>gc_destructor_fiber</literal>.
+    If this Fiber is suspended, a new one will be created to execute any
+    remaining destructors.
+    The previous <literal>gc_destructor_fiber</literal> will no longer be
+    referenced by the garbage collector and may be collected if it is not
+    referenced elsewhere.
+    Objects whose destructor are suspended will not be collected until the
+    destructor returns or the Fiber itself is collected.
+   </para>
    <note>
     <para>
      Destructors called during the script shutdown have HTTP headers already