Deploying to gh-pages from @ 0434204 🚀

Author: Girgias

_sources/php7/internal_types/functions/callables.rst.txt

@@ -86,16 +86,19 @@ Let detail the various FCC fields:
 .. warning:: Prior to PHP 7.3.0 there existed an ``initialized`` field. Now an FCC is considered initialized when
   ``function_handler`` is set to a non-null pointer.
 
+.. note:: As of PHP 8.3.0, the FCC holds a ``closure`` field and a dedicated API to handle storing userland callables.
+    This new API is described below.
+
 The *only* case where an FCC will be uninitialized is if the function is a trampoline, i.e. when the method
 of a class does not exist but is handled by the magic methods ``__call()``/``__callStatic()``.
 This is because a trampoline is freed by ZPP as it is a newly allocated ``zend_function`` struct with the
 op array copied, and is freed when called. To retrieve it manually use ``zend_is_callable_ex()``.
 
 .. warning:: It is not sufficient to just store the FCC to be able to call a user function at a later stage.
-   If the callable zval from the FCI is an object (because it has an ``__invoke`` method, is a ``Closure``,
-   or a trampoline) then a reference to the ``zend_object`` must also be stored, the refcount incremented,
-   and released as needed. Moreover, if the callable is a trampoline the ``function_handler`` must be copied
-   to be persisted between calls (see how SPL implements the storage of autoloading functions).
+    If the callable zval from the FCI is an object (because it has an ``__invoke`` method, is a ``Closure``,
+    or a trampoline) then a reference to the ``zend_object`` must also be stored, the refcount incremented,
+    and released as needed. Moreover, if the callable is a trampoline the ``function_handler`` must be copied
+    to be persisted between calls (see how SPL implements the storage of autoloading functions).
 
 .. note:: To determine that two user functions are equal comparing the ``function_handler``, ``object``,
     ``called_scope``, ``calling_scope``, and the pointer to the ``zend_object`` for closures is generally sufficient.
@@ -108,10 +111,6 @@ op array copied, and is freed when called. To retrieve it manually use ``zend_is
   Moreover, if a reference to the closure is kept, this must be called *prior* to freeing the closure,
   as the trampoline will partially refer to a ``zend_function *`` entry in the closure CE.
 
-..
-    This API is still being worked on and won't be usable for a year
-    note:: As of PHP 8.3.0, the FCC holds a ``closure`` field and a dedicated API to handle storing userland callables.
-
 Zend Engine API for callables
 -----------------------------
 
@@ -120,23 +119,18 @@ We will describe the various APIs needed to deal with callables in PHP.
 
 First of all, to check if an FCI is initialized use the ``ZEND_FCI_INITIALIZED(fci)`` macro.
 
-.. And, as of PHP 8.3.0, the ``ZEND_FCC_INITIALIZED(fcc)`` macro to check if an FCC is initialized.
-
 If you have a correctly initialized and set up FCI/FCC pair for a callable you can call it directly by using the
 ``zend_call_function(zend_fcall_info *fci, zend_fcall_info_cache *fci_cache)`` function.
 
 .. warning:: The ``zend_fcall_info_arg*()`` and ``zend_fcall_info_call()`` APIs should not be used.
     The ``zval *args`` parameter does *not* set the ``params`` field of the FCI directly.
-    Instead it expect it to be a PHP array (IS_ARRAY zval) containing positional arguments, which will be reallocated
-    into a new C array. As the ``named_params`` field accepts positional arguments, it is generally better to simply
-    assign the HashTable pointer of this argument to this field.
+    Instead it expect it to be a PHP array (``IS_ARRAY`` zval) containing positional arguments,
+    which will be reallocated into a new C array.
+    As the ``named_params`` field accepts positional arguments, it is generally better to simply
+    assign the ``HashTable`` pointer of this argument to this field.
     Moreover, as arguments to a userland call are predetermined and stack allocated it is better to assign the
     ``params`` and ``param_count`` fields directly.
 
-..
-    note:: As of PHP 8.3.0, the ``zend_call_function_with_return_value(*fci, *fcc, zval *retval)`` function has
-    been added to replace the usage of ``zend_fcall_info_call(fci, fcc, retval, NULL)``.
-
 In the more likely case where you just have a callable zval, you have the choice of a couple different options
 depending on the use case.
 
@@ -176,3 +170,30 @@ functions::
 And specific parameter number variations for the latter.
 
 .. note:: If you want to call a method on an object if it exists use the ``zend_call_method_if_exists()`` function.
+
+New FCI/FCC API in PHP 8.3.0
+----------------------------
+
+PHP 8.3.0 added some new APIs to improve the handling and storage of FCCs and userland callables.
+This was achieved by adding the ``closure`` field to the FCC.
+
+First of all a new ``ZEND_FCC_INITIALIZED(fcc)`` macro to check if an FCC is initialized was added,
+this is helper similar to the ``ZEND_FCI_INITIALIZED(fci)`` macro.
+
+The ``zend_fcc_addref()`` and ``zend_fcc_dup()`` functions will do all the necessary reference increments
+to safely store an FCC in an internal object.
+The ``zend_fcc_equals()`` function, can be used if two FCCs are equal or not, which also supports trampolines.
+The ``zend_fcc_dtor()`` function must be used when releasing an FCC that was copied for internal storage.
+
+If an internal object stores an FCC the ``get_gc`` object handler must be defined,
+and add it to the GC buffer via ``zend_get_gc_buffer_add_fcc()``.
+
+The ``zend_get_callable_zval_from_fcc()`` function will create a callable zval that can be returned to userland.
+
+When calling a stored FCC the
+``void zend_call_known_fcc(zend_fcall_info_cache *fcc, zval *retval_ptr, uint32_t param_count, zval *params, HashTable *named_params)``
+should be used, as it will duplicate the op array of a trampoline.
+The remaining parameters will be used to construct the FCI.
+
+.. note:: The ``zend_call_function_with_return_value(*fci, *fcc, zval *retval)`` function was also added in PHP 8.3.0
+    to replace the usage of ``zend_fcall_info_call(fci, fcc, retval, NULL)``.

php7/internal_types/functions.html

@@ -48,6 +48,7 @@ <h1>Functions<a class="headerlink" href="#functions" title="Link to this heading
 <li class="toctree-l2"><a class="reference internal" href="functions/callables.html#structure-of-zend-fcall-info">Structure of <code class="docutils literal notranslate"><span class="pre">zend_fcall_info</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="functions/callables.html#structure-of-zend-fcall-info-cache">Structure of <code class="docutils literal notranslate"><span class="pre">zend_fcall_info_cache</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="functions/callables.html#zend-engine-api-for-callables">Zend Engine API for callables</a></li>
+<li class="toctree-l2"><a class="reference internal" href="functions/callables.html#new-fci-fcc-api-in-php-8-3-0">New FCI/FCC API in PHP 8.3.0</a></li>
 </ul>
 </li>
 </ul>

php7/internal_types/functions/callables.html

@@ -121,6 +121,11 @@ <h2>Structure of <code class="docutils literal notranslate"><span class="pre">ze
 <p>Prior to PHP 7.3.0 there existed an <code class="docutils literal notranslate"><span class="pre">initialized</span></code> field. Now an FCC is considered initialized when
 <code class="docutils literal notranslate"><span class="pre">function_handler</span></code> is set to a non-null pointer.</p>
 </div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>As of PHP 8.3.0, the FCC holds a <code class="docutils literal notranslate"><span class="pre">closure</span></code> field and a dedicated API to handle storing userland callables.
+This new API is described below.</p>
+</div>
 <p>The <em>only</em> case where an FCC will be uninitialized is if the function is a trampoline, i.e. when the method
 of a class does not exist but is handled by the magic methods <code class="docutils literal notranslate"><span class="pre">__call()</span></code>/<code class="docutils literal notranslate"><span class="pre">__callStatic()</span></code>.
 This is because a trampoline is freed by ZPP as it is a newly allocated <code class="docutils literal notranslate"><span class="pre">zend_function</span></code> struct with the
@@ -160,9 +165,10 @@ <h2>Zend Engine API for callables<a class="headerlink" href="#zend-engine-api-fo
 <p class="admonition-title">Warning</p>
 <p>The <code class="docutils literal notranslate"><span class="pre">zend_fcall_info_arg*()</span></code> and <code class="docutils literal notranslate"><span class="pre">zend_fcall_info_call()</span></code> APIs should not be used.
 The <code class="docutils literal notranslate"><span class="pre">zval</span> <span class="pre">*args</span></code> parameter does <em>not</em> set the <code class="docutils literal notranslate"><span class="pre">params</span></code> field of the FCI directly.
-Instead it expect it to be a PHP array (IS_ARRAY zval) containing positional arguments, which will be reallocated
-into a new C array. As the <code class="docutils literal notranslate"><span class="pre">named_params</span></code> field accepts positional arguments, it is generally better to simply
-assign the HashTable pointer of this argument to this field.
+Instead it expect it to be a PHP array (<code class="docutils literal notranslate"><span class="pre">IS_ARRAY</span></code> zval) containing positional arguments,
+which will be reallocated into a new C array.
+As the <code class="docutils literal notranslate"><span class="pre">named_params</span></code> field accepts positional arguments, it is generally better to simply
+assign the <code class="docutils literal notranslate"><span class="pre">HashTable</span></code> pointer of this argument to this field.
 Moreover, as arguments to a userland call are predetermined and stack allocated it is better to assign the
 <code class="docutils literal notranslate"><span class="pre">params</span></code> and <code class="docutils literal notranslate"><span class="pre">param_count</span></code> fields directly.</p>
 </div>
@@ -207,6 +213,29 @@ <h2>Zend Engine API for callables<a class="headerlink" href="#zend-engine-api-fo
 <p>If you want to call a method on an object if it exists use the <code class="docutils literal notranslate"><span class="pre">zend_call_method_if_exists()</span></code> function.</p>
 </div>
 </section>
+<section id="new-fci-fcc-api-in-php-8-3-0">
+<h2>New FCI/FCC API in PHP 8.3.0<a class="headerlink" href="#new-fci-fcc-api-in-php-8-3-0" title="Link to this heading">¶</a></h2>
+<p>PHP 8.3.0 added some new APIs to improve the handling and storage of FCCs and userland callables.
+This was achieved by adding the <code class="docutils literal notranslate"><span class="pre">closure</span></code> field to the FCC.</p>
+<p>First of all a new <code class="docutils literal notranslate"><span class="pre">ZEND_FCC_INITIALIZED(fcc)</span></code> macro to check if an FCC is initialized was added,
+this is helper similar to the <code class="docutils literal notranslate"><span class="pre">ZEND_FCI_INITIALIZED(fci)</span></code> macro.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">zend_fcc_addref()</span></code> and <code class="docutils literal notranslate"><span class="pre">zend_fcc_dup()</span></code> functions will do all the necessary reference increments
+to safely store an FCC in an internal object.
+The <code class="docutils literal notranslate"><span class="pre">zend_fcc_equals()</span></code> function, can be used if two FCCs are equal or not, which also supports trampolines.
+The <code class="docutils literal notranslate"><span class="pre">zend_fcc_dtor()</span></code> function must be used when releasing an FCC that was copied for internal storage.</p>
+<p>If an internal object stores an FCC the <code class="docutils literal notranslate"><span class="pre">get_gc</span></code> object handler must be defined,
+and add it to the GC buffer via <code class="docutils literal notranslate"><span class="pre">zend_get_gc_buffer_add_fcc()</span></code>.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">zend_get_callable_zval_from_fcc()</span></code> function will create a callable zval that can be returned to userland.</p>
+<p>When calling a stored FCC the
+<code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">zend_call_known_fcc(zend_fcall_info_cache</span> <span class="pre">*fcc,</span> <span class="pre">zval</span> <span class="pre">*retval_ptr,</span> <span class="pre">uint32_t</span> <span class="pre">param_count,</span> <span class="pre">zval</span> <span class="pre">*params,</span> <span class="pre">HashTable</span> <span class="pre">*named_params)</span></code>
+should be used, as it will duplicate the op array of a trampoline.
+The remaining parameters will be used to construct the FCI.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">zend_call_function_with_return_value(*fci,</span> <span class="pre">*fcc,</span> <span class="pre">zval</span> <span class="pre">*retval)</span></code> function was also added in PHP 8.3.0
+to replace the usage of <code class="docutils literal notranslate"><span class="pre">zend_fcall_info_call(fci,</span> <span class="pre">fcc,</span> <span class="pre">retval,</span> <span class="pre">NULL)</span></code>.</p>
+</div>
+</section>
 </section>