Document changes related to Fibers and destructors (#4060)

Author: arnaud-lb

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> 
 

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