sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-15 16:38:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update markup (especially for examples)

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@293664 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Hannes Magnusson 2010-01-17 20:56:29 +00:00
parent dc2ee42a3b
commit c61ad553a8
1 changed files with 133 additions and 123 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

256
features/gc.xml
View file

@ -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>