reference/var/functions/debug-zval-dump.xml
d08d2e887fdc229f16748df96450c9b68c9a3076
d08d2e887fdc229f16748df96450c9b68c9a3076
...
...
@@ -3,16 +3,19 @@
3
3
<refentry xml:id="function.debug-zval-dump" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>debug_zval_dump</refname>
6
-
<refpurpose>Dumps a string representation of an internal zend value to output</refpurpose>
6
+
<refpurpose>Dumps a string representation of an internal zval structure to output</refpurpose>
7
7
</refnamediv>
8
8
<refsect1 role="description">
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
11
<type>void</type><methodname>debug_zval_dump</methodname>
12
-
<methodparam><type>mixed</type><parameter>variable</parameter></methodparam>
12
+
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
13
+
<methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
13
14
</methodsynopsis>
14
15
<para>
15
-
Dumps a string representation of an internal zend value to output.
16
+
Dumps a string representation of an internal zval (Zend value) structure to output.
17
+
This is mostly useful for understanding or debugging implementation details of the
18
+
Zend Engine or PHP extensions.
16
19
</para>
17
20
</refsect1>
18
21
<refsect1 role="parameters">
...
...
@@ -20,10 +23,18 @@
20
23
<para>
21
24
<variablelist>
22
25
<varlistentry>
23
-
<term><parameter>variable</parameter></term>
26
+
<term><parameter>value</parameter></term>
24
27
<listitem>
25
28
<para>
26
-
The variable being evaluated.
29
+
The variable or value to dump.
30
+
</para>
31
+
</listitem>
32
+
</varlistentry>
33
+
<varlistentry>
34
+
<term><parameter>values</parameter></term>
35
+
<listitem>
36
+
<para>
37
+
Further variables or values to dump.
27
38
</para>
28
39
</listitem>
29
40
</varlistentry>
...
...
@@ -44,68 +55,60 @@
44
55
<programlisting role="php">
45
56
<![CDATA[
46
57
<?php
47
-
$var1 = 'Hello World';
48
-
$var2 = '';
49
-
50
-
$var2 =& $var1;
58
+
$var1 = 'Hello';
59
+
$var1 .= ' World';
60
+
$var2 = $var1;
51
61
52
-
debug_zval_dump(&$var1);
62
+
debug_zval_dump($var1);
53
63
?>
54
64
]]>
55
65
</programlisting>
56
66
&example.outputs;
57
67
<screen>
58
68
<![CDATA[
59
-
&string(11) "Hello World" refcount(3)
69
+
string(11) "Hello World" refcount(3)
60
70
]]>
61
71
</screen>
62
72
</example>
63
73
</para>
64
74
<note>
65
-
<title>Beware the <literal>refcount</literal></title>
75
+
<title>Understanding the <literal>refcount</literal></title>
66
76
<para>
67
-
The <literal>refcount</literal> value returned by this function is
68
-
non-obvious in certain circumstances. For example, a developer might
69
-
expect the above example to indicate a <literal>refcount</literal> of
70
-
<literal>2</literal>. The third reference is created when actually
71
-
calling <function>debug_zval_dump</function>.
77
+
The <literal>refcount</literal> value shown by this function may be
78
+
surprising without a detailed understanding of the engine's implementation.
72
79
</para>
73
80
<para>
74
-
This behavior is further compounded when a variable is not passed to
75
-
<function>debug_zval_dump</function> by reference. To illustrate, consider
76
-
a slightly modified version of the above example:
81
+
The Zend Engine uses reference counting for two different purposes:
77
82
</para>
78
83
<para>
79
-
<example>
80
-
<title/>
81
-
<programlisting role="php">
82
-
<![CDATA[
83
-
<?php
84
-
$var1 = 'Hello World';
85
-
$var2 = '';
86
-
87
-
$var2 =& $var1;
88
-
89
-
debug_zval_dump($var1); // not passed by reference, this time
90
-
?>
91
-
]]>
92
-
</programlisting>
93
-
&example.outputs;
94
-
<screen>
95
-
<![CDATA[
96
-
string(11) "Hello World" refcount(1)
97
-
]]>
98
-
</screen>
99
-
</example>
84
+
<simplelist>
85
+
<member>
86
+
Optimizing memory usage using a technique called "copy on write",
87
+
where multiple variables holding the same value point to the same copy
88
+
in memory. When any of the variables is modified, it is pointed to a new
89
+
copy in memory, and the reference count on the original is decreased by 1.
90
+
</member>
91
+
<member>
92
+
Tracking variables which have been assigned or passed by reference (see
93
+
<link linkend="language.references">References Explained</link>). This
94
+
refcount is stored on a separate reference zval, pointing to the zval
95
+
for the current value. This additional zval is not currently shown by
96
+
<function>debug_zval_dump</function>.
97
+
</member>
98
+
</simplelist>
100
99
</para>
101
100
<para>
102
-
Why <literal>refcount(1)</literal>? Because a copy of <literal>$var1</literal> is
103
-
being made, when the function is called.
101
+
Because <function>debug_zval_dump</function> takes its input as normal
102
+
parameters, passed by value, the copy on write technique will be used
103
+
to pass them: rather than copying the data, the refcount will be increased
104
+
by one for the lifetime of the function call. If the function modified the
105
+
parameter after receiving it, then a copy would be made; since it does not,
106
+
it will show a refcount one higher than in the calling scope.
104
107
</para>
105
108
<para>
106
-
This function becomes even <emphasis>more</emphasis> confusing when a
107
-
variable with a <literal>refcount</literal> of <literal>1</literal> is
108
-
passed (by copy/value):
109
+
The parameter passing also prevents <function>debug_zval_dump</function>
110
+
showing variables which have been assigned by reference. To illustrate,
111
+
consider a slightly modified version of the above example:
109
112
</para>
110
113
<para>
111
114
<example>
...
...
@@ -113,7 +116,11 @@ string(11) "Hello World" refcount(1)
113
116
<programlisting role="php">
114
117
<![CDATA[
115
118
<?php
116
-
$var1 = 'Hello World';
119
+
$var1 = 'Hello';
120
+
$var1 .= ' World';
121
+
// Point three variables as references to the same value
122
+
$var2 =& $var1;
123
+
$var3 =& $var1;
117
124
118
125
debug_zval_dump($var1);
119
126
?>
...
...
@@ -128,25 +135,18 @@ string(11) "Hello World" refcount(2)
128
135
</example>
129
136
</para>
130
137
<para>
131
-
A <literal>refcount</literal> of <literal>2</literal>, here, is extremely
132
-
non-obvious. Especially considering the above examples. So what's
133
-
happening?
138
+
Although <varname>$var1</varname>, <varname>$var2</varname>, and
139
+
<varname>$var3</varname> are linked as references, only the
140
+
<emphasis>value</emphasis> is passed to <function>debug_zval_dump</function>.
141
+
That value is used once by the set of references, and once inside the
142
+
<function>debug_zval_dump</function>, so shows a refcount of 2.
134
143
</para>
135
144
<para>
136
-
When a variable has a single reference (as did <literal>$var1</literal>
137
-
before it was used as an argument to <function>debug_zval_dump</function>),
138
-
PHP's engine optimizes the manner in which it is passed to a function.
139
-
Internally, PHP treats <literal>$var1</literal> like a reference (in that
140
-
the <literal>refcount</literal> is increased for the scope of this
141
-
function), with the caveat that <emphasis>if</emphasis> the passed reference
142
-
happens to be written to, a copy is made, but only at the moment of
143
-
writing. This is known as "copy on write."
144
-
</para>
145
-
<para>
146
-
So, if <function>debug_zval_dump</function> happened to write to its sole
147
-
parameter (and it doesn't), then a copy would be made. Until then, the
148
-
parameter remains a reference, causing the <literal>refcount</literal> to
149
-
be incremented to <literal>2</literal> for the scope of the function call.
145
+
Further complications arise because of optimisations made in the engine for
146
+
different data types. Some types such as integers do not use "copy on write",
147
+
so do not show a refcount at all. In other cases, the refcount shows extra
148
+
copies used internally, such as when a literal string or array is stored as
149
+
part of a code instruction.
150
150
</para>
151
151
</note>
152
152
</refsect1>
...
...
@@ -162,7 +162,6 @@ string(11) "Hello World" refcount(2)
162
162
</para>
163
163
</refsect1>
164
164
</refentry>
165
-
166
165
<!-- Keep this comment at the end of the file
167
166
Local variables:
168
167
mode: sgml
169
168