mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
Update markup (especially for examples)
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@293664 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
parent
dc2ee42a3b
commit
c61ad553a8
1 changed files with 133 additions and 123 deletions
256
features/gc.xml
256
features/gc.xml
|
@ -29,46 +29,52 @@
|
|||
<para>
|
||||
A zval container is created when a new variable is created with a constant
|
||||
value, such as:
|
||||
<programlisting role="php">
|
||||
<example>
|
||||
<title>Creating a new zval container</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$a = "new string";
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
In this case, the new symbol name, "a", is created in the current scope,
|
||||
and a new variable container is created with type "string", value "new
|
||||
string". The "is_ref" bit is by default set to "false" because no
|
||||
user-land reference has been created. The "refcount" is set to "1" as
|
||||
In this case, the new symbol name, <literal>a</literal>, is created in the current scope,
|
||||
and a new variable container is created with the type <type>string</type> and the value
|
||||
<literal>new string</literal>. The "is_ref" bit is by default set to &false; because no
|
||||
user-land reference has been created. The "refcount" is set to <literal>1</literal> as
|
||||
there is only one symbol that makes use of this variable container. Note
|
||||
that if "refcount" is "1", "is_ref" is always "false". If you have <link
|
||||
that if "refcount" is <literal>1</literal>, "is_ref" is always &false;. If you have <link
|
||||
xlink:href='&url.xdebug;'>Xdebug</link> installed, you can display this
|
||||
information by calling:
|
||||
information by calling <function>xdebug_debug_zval</function>.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="php">
|
||||
<example>
|
||||
<title>Displaying zval information</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
xdebug_debug_zval('a');
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
which displays:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="shell">
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
a: (refcount=1, is_ref=0)='new string'
|
||||
</programlisting>
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
Assigning this variable to another variable name increases the refcount:
|
||||
Assigning this variable to another variable name will increase the refcount.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="php">
|
||||
<example>
|
||||
<title>Increasing refcount of a zval</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$a = "new string";
|
||||
|
@ -76,19 +82,19 @@ $b = $a;
|
|||
xdebug_debug_zval( 'a' );
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
which displays:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="shell">
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
a: (refcount=2, is_ref=0)='new string'
|
||||
</programlisting>
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
The refcount is "2" here, because the same variable container is linked
|
||||
with both "a" and "b". PHP is smart enough not to copy the actual variable
|
||||
The refcount is <literal>2</literal> here, because the same variable container is linked
|
||||
with both <varname>a</varname> and <varname>b</varname>.
|
||||
PHP is smart enough not to copy the actual variable
|
||||
container when it is not necessary. Variable containers get destroyed when
|
||||
the "refcount" reaches zero. The "refcount" gets decreased by one when any
|
||||
symbol linked to the variable container leaves the scope (e.g. when the
|
||||
|
@ -96,7 +102,9 @@ a: (refcount=2, is_ref=0)='new string'
|
|||
The following example shows this:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="php">
|
||||
<example>
|
||||
<title>Decreasing zval refcount</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$a = "new string";
|
||||
|
@ -106,19 +114,18 @@ unset( $b, $c );
|
|||
xdebug_debug_zval( 'a' );
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
which displays:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="shell">
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
a: (refcount=3, is_ref=0)='new string'
|
||||
a: (refcount=1, is_ref=0)='new string'
|
||||
</programlisting>
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
If we now call "unset( $a );", the variable container, including the type
|
||||
If we now call <literal>unset($a);</literal>, the variable container, including the type
|
||||
and value, will be removed from memory.
|
||||
</para>
|
||||
|
||||
|
@ -126,49 +133,51 @@ a: (refcount=1, is_ref=0)='new string'
|
|||
<title>Compound Types</title>
|
||||
|
||||
<para>
|
||||
Things get a tad more complex with compound types such as arrays and
|
||||
objects. Instead of a scalar value, arrays and objects store their
|
||||
Things get a tad more complex with compound types such as <type>array</type>s and
|
||||
<type>object</type>s. Instead of a <type>scalar</type> value, <type>array</type>s
|
||||
and <type>object</type>s store their
|
||||
properties in a symbol table of their own. This means that the following
|
||||
example creates three zval containers:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="php">
|
||||
<example>
|
||||
<title>Creating a <type>array</type> zval</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$a = array( 'meaning' => 'life', 'number' => 42 );
|
||||
xdebug_debug_zval( 'a' );
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
which displays (after formatting):
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="shell">
|
||||
</programlisting>
|
||||
&example.outputs.similar;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
a: (refcount=1, is_ref=0)=array (
|
||||
'meaning' => (refcount=1, is_ref=0)='life',
|
||||
'number' => (refcount=1, is_ref=0)=42
|
||||
)
|
||||
</programlisting>
|
||||
]]>
|
||||
</screen>
|
||||
<para>Or graphically</para>
|
||||
<mediaobject>
|
||||
<alt>Zvals for a simple array</alt>
|
||||
<imageobject>
|
||||
<imagedata fileref="en/features/figures/simple-array.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
Or graphically:
|
||||
<mediaobject>
|
||||
<alt>Zvals for a simple array</alt>
|
||||
<imageobject>
|
||||
<imagedata fileref="en/features/figures/simple-array.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
</para>
|
||||
<para>
|
||||
The three zval containers are: "a", "meaning", and "number". Similar rules
|
||||
apply for increasing and decreasing "refcounts". Below, we add another
|
||||
The three zval containers are: <varname>a</varname>, <varname>meaning</varname>, and <varname>number</varname>.
|
||||
Similar rules apply for increasing and decreasing "refcounts". Below, we add another
|
||||
element to the array, and set its value to the contents of an already
|
||||
existing element:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="php">
|
||||
<example>
|
||||
<title>Adding already existing element to an array</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$a = array( 'meaning' => 'life', 'number' => 42 );
|
||||
|
@ -176,32 +185,30 @@ $a['life'] = $a['meaning'];
|
|||
xdebug_debug_zval( 'a' );
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
which displays (after formatting):
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="shell">
|
||||
</programlisting>
|
||||
&example.outputs.similar;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
a: (refcount=1, is_ref=0)=array (
|
||||
'meaning' => (refcount=2, is_ref=0)='life',
|
||||
'number' => (refcount=1, is_ref=0)=42,
|
||||
'life' => (refcount=2, is_ref=0)='life'
|
||||
)
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Or graphically:
|
||||
<mediaobject>
|
||||
<alt>Zvals for a simple array with a reference</alt>
|
||||
<imageobject>
|
||||
<imagedata fileref="en/features/figures/simple-array2.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
]]>
|
||||
</screen>
|
||||
<para>Or graphically</para>
|
||||
<mediaobject>
|
||||
<alt>Zvals for a simple array with a reference</alt>
|
||||
<imageobject>
|
||||
<imagedata fileref="en/features/figures/simple-array2.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
From the above Xdebug output, we see that both the old and new array
|
||||
element now point to a zval container whose "refcount" is "2". Of course,
|
||||
element now point to a zval container whose "refcount" is
|
||||
<literal>2</literal>. Of course,
|
||||
there are now two zval containers, but they are the same one. The
|
||||
<function>xdebug_debug_zval</function> function does not show this, but
|
||||
you could see this by also displaying the memory pointer. Removing an
|
||||
|
@ -211,7 +218,9 @@ a: (refcount=1, is_ref=0)=array (
|
|||
container is removed from memory. Again, an example to show this:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="php">
|
||||
<example>
|
||||
<title>Removing an element from an array</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$a = array( 'meaning' => 'life', 'number' => 42 );
|
||||
|
@ -220,25 +229,26 @@ unset( $a['meaning'], $a['number'] );
|
|||
xdebug_debug_zval( 'a' );
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
which displays (after formatting):
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="shell">
|
||||
</programlisting>
|
||||
&example.outputs.similar;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
a: (refcount=1, is_ref=0)=array (
|
||||
'life' => (refcount=1, is_ref=0)='life'
|
||||
)
|
||||
</programlisting>
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
Now, things get interesting if we add the array itself as an element of
|
||||
the array, which we do in the next example, in which I also snuck in a
|
||||
the array, which we do in the next example, in which we also sneak in a
|
||||
reference operator, since otherwise PHP would create a copy:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="php">
|
||||
<example>
|
||||
<title>Adding the array itself as an element of it self</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$a = array( 'one' );
|
||||
|
@ -246,31 +256,28 @@ $a[] =& $a;
|
|||
xdebug_debug_zval( 'a' );
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
which displays (after formatting):
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="shell">
|
||||
</programlisting>
|
||||
&example.outputs.similar;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
a: (refcount=2, is_ref=1)=array (
|
||||
0 => (refcount=1, is_ref=0)='one',
|
||||
1 => (refcount=2, is_ref=1)=...
|
||||
)
|
||||
</programlisting>
|
||||
]]>
|
||||
</screen>
|
||||
<para>Or graphically</para>
|
||||
<mediaobject>
|
||||
<alt>Zvals for an array with a circular reference</alt>
|
||||
<imageobject>
|
||||
<imagedata fileref="en/features/figures/loop-array.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
Or graphically:
|
||||
<mediaobject>
|
||||
<alt>Zvals for an array with a circular reference</alt>
|
||||
<imageobject>
|
||||
<imagedata fileref="en/features/figures/loop-array.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
</para>
|
||||
<para>
|
||||
You can see that the array variable ("a") as well as the second element
|
||||
("1") now point to a variable container that has a "refcount" of "2". The
|
||||
You can see that the array variable (<varname>a</varname>) as well as the second element
|
||||
(<varname>1</varname>) now point to a variable container that has a "refcount" of <literal>2</literal>. The
|
||||
"..." in the display above shows that there is recursion involved, which,
|
||||
of course, in this case means that the "..." points back to the original
|
||||
array.
|
||||
|
@ -278,26 +285,29 @@ a: (refcount=2, is_ref=1)=array (
|
|||
<para>
|
||||
Just like before, unsetting a variable removes the symbol, and the
|
||||
reference count of the variable container it points to is decreased by
|
||||
one. So, if we unset variable $a after running the above code, the
|
||||
reference count of the variable container that $a and element "1" point to
|
||||
one. So, if we unset variable <varname>$a</varname> after running the above code, the
|
||||
reference count of the variable container that <varname>$a</varname> and element "1" point to
|
||||
gets decreased by one, from "2" to "1". This can be represented as:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="shell">
|
||||
<example>
|
||||
<title>Unsetting <varname>$a</varname></title>
|
||||
<screen>
|
||||
<![CDATA[
|
||||
(refcount=1, is_ref=1)=array (
|
||||
0 => (refcount=1, is_ref=0)='one',
|
||||
1 => (refcount=1, is_ref=1)=...
|
||||
)
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Or graphically:
|
||||
<mediaobject>
|
||||
<alt>Zvals after removal of array with a circular reference demonstrating the memory leak</alt>
|
||||
<imageobject>
|
||||
<imagedata fileref="en/features/figures/leak-array.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
]]>
|
||||
</screen>
|
||||
<para>Or graphically</para>
|
||||
<mediaobject>
|
||||
<alt>Zvals after removal of array with a circular reference demonstrating the memory leak</alt>
|
||||
<imageobject>
|
||||
<imagedata fileref="en/features/figures/leak-array.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
</example>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
|
|
Loading…
Reference in a new issue