cvs: phpdoc /en/reference/var/functions debug-zval-dump.xml

sean Wed Aug 31 16:01:40 2005 EDT Modified files: /phpdoc/en/reference/var/functions debug-zval-dump.xml Log: change example and add (big) note on refcount http://cvs.php.net/diff.php/phpdoc/en/reference/var/functions/debug-zval-dump.xml?r1=1.3&r2=1.4&ty=u Index: phpdoc/en/reference/var/functions/debug-zval-dump.xml diff -u phpdoc/en/reference/var/functions/debug-zval-dump.xml:1.3 phpdoc/en/reference/var/functions/debug-zval-dump.xml:1.4 --- phpdoc/en/reference/var/functions/debug-zval-dump.xml:1.3 Mon Apr 11 04:27:31 2005 +++ phpdoc/en/reference/var/functions/debug-zval-dump.xml Wed Aug 31 16:01:36 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <refentry id="function.debug-zval-dump"> <refnamediv> <refname>debug_zval_dump</refname> @@ -49,18 +49,106 @@ $var2 =& $var1; -debug_zval_dump($var1); +debug_zval_dump(&$var1); ?> ]]> </programlisting> &example.outputs; <screen> <![CDATA[ -string(11) "Hello World" refcount(1) +string(11) "Hello World" refcount(3) ]]> </screen> </example> </para> + <note> + <title>Beware the <literal>refcount</literal></title> + <para> + The <literal>refcount</literal> value returned by this function is + non-obvious in certain circumstances. For example, a developer might + expect the above example to indicate a <literal>refcount</literal> of + <literal>2</literal>. The third reference is created when actually + calling <function>debug_zval_dump</function>. + </para> + <para> + This behavior is further compounded when a variable is not passed to + <function>debug_zval_dump</function> by reference. To illustrate, consider + a slightly modified version of the above example: + </para> + <para> + <example> + <title/> + <programlisting role="php"> +<![CDATA[ +<?php +$var1 = 'Hello World'; +$var2 = ''; + +$var2 =& $var1; + +debug_zval_dump($var1); // not passed by reference, this time +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +string(11) "Hello World" refcount(1) +]]> + </screen> + </example> + </para> + <para> + Why <literal>refcount(1)</literal>? Because a copy of <literal>$var1</literal> is + being made, when the function is called. + </para> + <para> + This function becomes even <emphasis>more</emphasis> confusing when a + variable with a <literal>refcount</literal> of <literal>1</literal> is + passed (by copy/value): + </para> + <para> + <example> + <title/> + <programlisting role="php"> +<![CDATA[ +<?php +$var1 = 'Hello World'; + +debug_zval_dump($var1); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +string(11) "Hello World" refcount(2) +]]> + </screen> + </example> + </para> + <para> + A <literal>refcount</literal> of <literal>2</literal>, here, is extremely + non-obvious. Especially considering the above examples. So what's + happening? + </para> + <para> + When a variable has a single reference (as did <literal>$var1</literal> + before it was used as an argument to <function>debug_zval_dump</function>), + PHP's engine optimizes the manner in which it is passed to a function. + Internally, PHP treats <literal>$var1</literal> like a reference (in that + the <literal>refcount</literal> is increased for the scope of this + function, with the caveat that <emphasis>if</emphasis> the passed reference + happens to be written to, a copy is made, but only at the moment of + writing. This is known as "copy on write." + </para> + <para> + So, if <function>debug_zval_dump</function> happened to write to its sole + parameter (and it doesn't), then a copy would be made. Until then, the + parameter remains a reference, causing the <literal>refcount</literal> to + be incremented to <literal>2</literal> for the scope of the function call. + </para> + </note> </refsect1> <refsect1 role="seealso"> &reftitle.seealso; @@ -69,6 +157,7 @@ <member><function>var_dump</function></member> <member><function>debug_backtrace</function></member> <member><link linkend="language.references">References Explained</link></member> + <member><ulink url="http://www.zend.com/zend/art/ref-count.php">Reference Counting and Aliasing (by Andi Gutmans)</ulink></member> </simplelist> </para> </refsect1>