1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.debug-zval-dump" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>debug_zval_dump</refname>
<refpurpose>Dumps a string representation of an internal zval structure to output</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>debug_zval_dump</methodname>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
</methodsynopsis>
<para>
Dumps a string representation of an internal zval (Zend value) structure to output.
This is mostly useful for understanding or debugging implementation details of the
Zend Engine or PHP extensions.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
The variable or value to dump.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>values</parameter></term>
<listitem>
<para>
Further variables or values to dump.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.void;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>debug_zval_dump</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$var1 = 'Hello';
$var1 .= ' World';
$var2 = $var1;
debug_zval_dump($var1);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(11) "Hello World" refcount(3)
]]>
</screen>
</example>
</para>
<note>
<title>Understanding the <literal>refcount</literal></title>
<para>
The <literal>refcount</literal> value shown by this function may be
surprising without a detailed understanding of the engine's implementation.
</para>
<para>
The Zend Engine uses reference counting for two different purposes:
</para>
<para>
<simplelist>
<member>
Optimizing memory usage using a technique called "copy on write",
where multiple variables holding the same value point to the same copy
in memory. When any of the variables is modified, it is pointed to a new
copy in memory, and the reference count on the original is decreased by 1.
</member>
<member>
Tracking variables which have been assigned or passed by reference (see
<link linkend="language.references">References Explained</link>). This
refcount is stored on a separate reference zval, pointing to the zval
for the current value. This additional zval is not currently shown by
<function>debug_zval_dump</function>.
</member>
</simplelist>
</para>
<para>
Because <function>debug_zval_dump</function> takes its input as normal
parameters, passed by value, the copy on write technique will be used
to pass them: rather than copying the data, the refcount will be increased
by one for the lifetime of the function call. If the function modified the
parameter after receiving it, then a copy would be made; since it does not,
it will show a refcount one higher than in the calling scope.
</para>
<para>
The parameter passing also prevents <function>debug_zval_dump</function>
showing variables which have been assigned by reference. To illustrate,
consider a slightly modified version of the above example:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$var1 = 'Hello';
$var1 .= ' World';
// Point three variables as references to the same value
$var2 =& $var1;
$var3 =& $var1;
debug_zval_dump($var1);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(11) "Hello World" refcount(2)
]]>
</screen>
</informalexample>
</para>
<para>
Although <varname>$var1</varname>, <varname>$var2</varname>, and
<varname>$var3</varname> are linked as references, only the
<emphasis>value</emphasis> is passed to <function>debug_zval_dump</function>.
That value is used once by the set of references, and once inside the
<function>debug_zval_dump</function>, so shows a refcount of 2.
</para>
<para>
Further complications arise because of optimisations made in the engine for
different data types. Some types such as integers do not use "copy on write",
so do not show a refcount at all. In other cases, the refcount shows extra
copies used internally, such as when a literal string or array is stored as
part of a code instruction.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>var_dump</function></member>
<member><function>debug_backtrace</function></member>
<member><link linkend="language.references">References Explained</link></member>
<member><link xlink:href="&url.derick.references;">References Explained (by Derick Rethans)</link></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
|
