Skip to content

Commit b204256

Browse files
committed
Improve wording
1 parent cb95d10 commit b204256

File tree

1 file changed

+10
-8
lines changed

1 file changed

+10
-8
lines changed

Book/php7/internal_types/functions/callables.rst

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -97,10 +97,10 @@ op array copied, and is freed when called. To retrieve it manually use ``zend_is
9797
and released as needed. Moreover, if the callable is a trampoline the ``function_handler`` must be copied
9898
to be persisted between calls (see how SPL implements the storage of autoloading functions).
9999

100-
.. note:: To release a FCC you should use the ``void zend_release_fcall_info_cache(zend_fcall_info_cache *fcc)``
101-
function if maintain copies of a potential trampoline, as this will release the trampoline properly.
102-
Moreover, this needs to be called *prior* to freeing the closure, as the trampoline will partially refer to a
103-
``zend_function *`` entry in the closure CE.
100+
.. note:: In most cases an FCC does not need to be released, the exception is if the FCC may hold a trampoline
101+
in which case the ``void zend_release_fcall_info_cache(zend_fcall_info_cache *fcc)`` should be used to release it.
102+
Moreover, if a reference to the closure is kept, this must be called *prior* to freeing the closure,
103+
as the trampoline will partially refer to a ``zend_function *`` entry in the closure CE.
104104

105105
..
106106
This API is still being worked on and won't be usable for a year
@@ -120,10 +120,12 @@ If you have a correctly initialized and set up FCI/FCC pair for a callable you c
120120
``zend_call_function(zend_fcall_info *fci, zend_fcall_info_cache *fci_cache)`` function.
121121

122122
.. warning:: The ``zend_fcall_info_arg*()`` and ``zend_fcall_info_call()`` APIs should not be used.
123-
The reasons for this is because the ``zval *args`` parameter does *not* set the ``params`` field of the FCI,
124-
but is expected to be a PHP array containing positional arguments. If this is the case the ``named_params``
125-
field should be set instead. Moreover, those functions reallocate the parameters on the heap when generally
126-
the arguments are stack allocated because the call is only done once with predetermined arguments.
123+
The ``zval *args`` parameter does *not* set the ``params`` field of the FCI directly.
124+
Instead it expect it to be a PHP array (IS_ARRAY zval) containing positional arguments, which will be reallocated
125+
into a new C array. As the ``named_params`` field accepts positional arguments, it is generally better to simply
126+
assign the HashTable pointer of this argument to this field.
127+
Moreover, as arguments to a userland call are predetermined and stack allocated it is better to assign the
128+
``params`` and ``param_count`` fields directly.
127129

128130
..
129131
note:: As of PHP 8.3.0, the ``zend_call_function_with_return_value(*fci, *fcc, zval *retval)`` function has

0 commit comments

Comments
 (0)