Updating WinCache docs to include information about v1.1.0 features and API's.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@295806 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ruslan Yakushev 2010-03-03 19:44:05 +00:00
parent be4feedda9
commit 0034cb11ce
19 changed files with 416 additions and 4 deletions

View file

@ -15,7 +15,7 @@
functionality without any code modifications.
</para>
<para>
The Windows Cache Extension includes 3 different types of caches. The following describes
The Windows Cache Extension includes 5 different types of caches. The following describes
the purpose of each cache type and the benefits it provides.
</para>
<itemizedlist>
@ -33,7 +33,7 @@
</listitem>
<listitem>
<para>
<emphasis>File Cache</emphasis> - Even with the PHP bytecode cache enabled, the PHP engine
<emphasis>File Cache</emphasis> - Even with the PHP opcode cache enabled, the PHP engine
has to accesses the script files on a file system. When PHP scripts are stored on a remote
UNC file share, the file operations introduce a significant performance overhead.
The Windows Cache Extension for PHP includes a file cache that is used to store the content
@ -53,6 +53,21 @@
PHP engine has to perform.
</para>
</listitem>
<listitem>
<para>
<emphasis>User Cache (available since version 1.1.0)</emphasis> - PHP scripts can take advantage of
the shared memory cache by using the user cache API's. PHP objects and variables can be stored in the
user cache and then re-used on subsequent requests. This can be used to improve performance of PHP scripts
and to share the data across multiple PHP processes.
</para>
</listitem>
<listitem>
<para>
<emphasis>Session Handler (available since version 1.1.0)</emphasis> - The WinCache session handler can be used to
store the PHP session data in the shared memory cache. This avoids file system operations for reading
and writing session data, which improves performance when large amound of data is stored in PHP session.
</para>
</listitem>
</itemizedlist>
</preface>

View file

@ -138,6 +138,8 @@ Array
<member><function>wincache_rplist_fileinfo</function></member>
<member><function>wincache_rplist_meminfo</function></member>
<member><function>wincache_refresh_if_changed</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -96,6 +96,8 @@ Array
<member><function>wincache_rplist_fileinfo</function></member>
<member><function>wincache_rplist_meminfo</function></member>
<member><function>wincache_refresh_if_changed</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -151,6 +151,8 @@ Array
<member><function>wincache_rplist_fileinfo</function></member>
<member><function>wincache_rplist_meminfo</function></member>
<member><function>wincache_refresh_if_changed</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -96,6 +96,8 @@ Array
<member><function>wincache_rplist_fileinfo</function></member>
<member><function>wincache_rplist_meminfo</function></member>
<member><function>wincache_refresh_if_changed</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -81,6 +81,8 @@ wincache_refresh_if_changed(array($filename));
<member><function>wincache_ocache_meminfo</function></member>
<member><function>wincache_rplist_fileinfo</function></member>
<member><function>wincache_rplist_meminfo</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -101,6 +101,8 @@ Array
<member><function>wincache_ocache_meminfo</function></member>
<member><function>wincache_rplist_meminfo</function></member>
<member><function>wincache_refresh_if_changed</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -96,6 +96,8 @@ Array
<member><function>wincache_ocache_meminfo</function></member>
<member><function>wincache_rplist_fileinfo</function></member>
<member><function>wincache_refresh_if_changed</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -30,7 +30,7 @@
<listitem>
<para>
Store the variable using this <parameter>key</parameter> name. If a variable with same key is already present the function
will fail and return false. <parameter>key</parameter> is case sensitive. To override the value even if
will fail and return <literal>FALSE</literal>. <parameter>key</parameter> is case sensitive. To override the value even if
<parameter>key</parameter> is present use <function>wincache_ucache_set</function> function instad.
<parameter>key</parameter> can also take array of name => value pairs where names will be used as keys.
This can be used to add multiple values in the cache in one operation, thus avoiding race condition.
@ -118,7 +118,7 @@ string(3) "BAR"
<programlisting role="php">
<![CDATA[
<?php
$colors_array = array('green' => "5", 'Blue' => "6", 'yellow' => "7", 'cyan' => "8");
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_get('Blue'));
@ -146,6 +146,8 @@ string(1) "6"
<member><function>wincache_ucache_delete</function></member>
<member><function>wincache_ucache_clear</function></member>
<member><function>wincache_ucache_exists</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -68,6 +68,8 @@ bool(false)
<member><function>wincache_ucache_delete</function></member>
<member><function>wincache_ucache_get</function></member>
<member><function>wincache_ucache_exists</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -124,6 +124,8 @@ array(2) { [0]=> string(6) "yellow"
<member><function>wincache_ucache_get</function></member>
<member><function>wincache_ucache_clear</function></member>
<member><function>wincache_ucache_exists</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -72,6 +72,8 @@ bool(true)
<member><function>wincache_ucache_get</function></member>
<member><function>wincache_ucache_clear</function></member>
<member><function>wincache_ucache_delete</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -119,6 +119,8 @@ bool(true)
<member><function>wincache_ucache_delete</function></member>
<member><function>wincache_ucache_clear</function></member>
<member><function>wincache_ucache_exists</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -0,0 +1,177 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 295782 $ -->
<refentry xml:id="function.wincache-ucache-info" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_info</refname>
<refpurpose>
Retrieves information about data stored in the user cache
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>wincache_ucache_info</methodname>
<void/>
</methodsynopsis>
<para>
Retrieves information about data stored in the user cache.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Array of meta data about user cache &return.falseforfailure;
</para>
<para>
The array returned by this function contains the following elements:
<itemizedlist spacing="compact">
<listitem>
<simpara>
<literal>total_cache_uptime</literal> - total time in seconds that the user cache has been active
</simpara>
</listitem>
<listitem>
<simpara>
<literal>total_item_count</literal> - total number of elements that are currently in the user cache
</simpara>
</listitem>
<listitem>
<simpara>
<literal>total_hit_count</literal> - number of times the data has been served from the cache
</simpara>
</listitem>
<listitem>
<simpara>
<literal>total_miss_count</literal> - number of times the data has not been found in the cache
</simpara>
</listitem>
<listitem>
<para>
<literal>file_entries</literal> - an array that contains the information about all the cached items:
<itemizedlist spacing="compact">
<listitem>
<simpara>
<literal>key_name</literal> - name of the key which is used to store the data
</simpara>
</listitem>
<listitem>
<simpara>
<literal>value_type</literal> - type of value stored by the key
</simpara>
</listitem>
<listitem>
<simpara>
<literal>use_time</literal> - time in seconds since the file has been accessed in the opcode cache
</simpara>
</listitem>
<listitem>
<simpara>
<literal>last_check</literal> - time in seconds since the file has been checked for modifications
</simpara>
</listitem>
<listitem>
<simpara>
<literal>is_session</literal> - indicates if the data is a session variable
</simpara>
</listitem>
<listitem>
<simpara>
<literal>ttl_seconds</literal> - time remaining for the data to live in the cache, 0 meaning infinite
</simpara>
</listitem>
<listitem>
<simpara>
<literal>age_seconds</literal> - time elapsed from the time data has been added in the cache
</simpara>
</listitem>
<listitem>
<simpara>
<literal>hitcount</literal> - number of times data has been served from the cache
</simpara>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Using <function>wincache_ucache_info</function></title>
<programlisting role="php">
<![CDATA[
<?php
wincache_ucache_get('green');
wincache_ucache_set('green', 2922);
wincache_ucache_get('green');
wincache_ucache_get('green');
wincache_ucache_get('green');
print_r(wincache_ucache_info());
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Array
( [total_cache_uptime] => 0
[is_local_cache] =>
[total_item_count] => 1
[total_hit_count] => 3
[total_miss_count] => 1
[ucache_entries] => Array
( [1] => Array
(
[key_name] => green
[value_type] => long
[is_session] => 0
[ttl_seconds] => 0
[age_seconds] => 0 [hitcount] => 3
)
)
)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_fcache_meminfo</function></member>
<member><function>wincache_ocache_fileinfo</function></member>
<member><function>wincache_ocache_meminfo</function></member>
<member><function>wincache_rplist_meminfo</function></member>
<member><function>wincache_rplist_fileinfo</function></member>
<member><function>wincache_refresh_if_changed</function></member>
<member><function>wincache_ucache_meminfo</function></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
-->

View file

@ -150,6 +150,8 @@ string(1) "6"
<member><function>wincache_ucache_delete</function></member>
<member><function>wincache_ucache_clear</function></member>
<member><function>wincache_ucache_exists</function></member>
<member><function>wincache_ucache_meminfo</function></member>
<member><function>wincache_ucache_info</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -0,0 +1,125 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 290998 $ -->
<refentry xml:id="function.wincache-ucache-meminfo" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_meminfo</refname>
<refpurpose>
Retrieves information about user cache memory usage
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>wincache_ucache_meminfo</methodname>
<void/>
</methodsynopsis>
<para>
Retrieves information about memory usage by user cache.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Array of meta data about user cache memory usage &return.falseforfailure;
</para>
<para>
The array returned by this function contains the following elements:
<itemizedlist spacing="compact">
<listitem>
<simpara>
<literal>memory_total</literal> - amount of memory in bytes allocated for the user cache
</simpara>
</listitem>
<listitem>
<simpara>
<literal>memory_free</literal> - amount of free memory in bytes available for the user cache
</simpara>
</listitem>
<listitem>
<simpara>
<literal>num_used_blks</literal> - number of memory blocks used by the user cache
</simpara>
</listitem>
<listitem>
<simpara>
<literal>num_free_blks</literal> - number of free memory blocks available for the user cache
</simpara>
</listitem>
<listitem>
<simpara>
<literal>memory_overhead</literal> - amount of memory in bytes used for the user cache internal structures
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>wincache_ucache_meminfo</function> example</title>
<programlisting role="php">
<![CDATA[
<pre>
<?php
print_r(wincache_ucache_meminfo());
?>
</pre>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Array
(
[memory_total] => 5242880
[memory_free] => 5215056
[num_used_blks] => 6
[num_free_blks] => 3
[memory_overhead] => 176
)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_fcache_fileinfo</function></member>
<member><function>wincache_fcache_meminfo</function></member>
<member><function>wincache_ocache_fileinfo</function></member>
<member><function>wincache_rplist_fileinfo</function></member>
<member><function>wincache_rplist_meminfo</function></member>
<member><function>wincache_refresh_if_changed</function></member>
<member><function>wincache_ucache_info</function></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
-->

View file

@ -126,6 +126,22 @@
<entry>PHP_INI_SYSTEM</entry>
<entry>Available since WinCache 1.0.0</entry>
</row>
<row>
<entry><link linkend="ini.wincache.ucenabled">wincache.ucenabled</link></entry>
<entry>1</entry>
<entry>0</entry>
<entry>1</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry>Available since WinCache 1.1.0</entry>
</row>
<row>
<entry><link linkend="ini.wincache.namesalt">wincache.ucachesize</link></entry>
<entry>8</entry>
<entry>5</entry>
<entry>85</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry>Available since WinCache 1.1.0</entry>
</row>
</tbody>
</tgroup>
</table>
@ -316,6 +332,30 @@ wincache.ignorelist = "index.php|misc.php|admin.php"
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.wincache.ucenabled">
<term>
<parameter>wincache.ucenabled</parameter>
<type>boolean</type>
</term>
<listitem>
<simpara>
Enables or disables the user cache functionality.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.wincache.ucachesize">
<term>
<parameter>wincache.ucachesize</parameter>
<type>integer</type>
</term>
<listitem>
<simpara>
Defines the maximum memory size in megabytes that is allocated for the user cache. If the total
size of variables stored in the user cache exceeds the specified value, then the most stale variables
will be removed from the cache.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>

View file

@ -184,6 +184,33 @@ $user_allowed = array('DOMAIN\user1', 'DOMAIN\user2', 'DOMAIN\user3');
</simpara>
</note>
</para>
</section>
<section xml:id="wincache.sessionhandler">
<title>WinCache Session Handler</title>
<para>
The WinCache session handler (available since WinCache 1.1.0) can be used to configure PHP to store the session data in shared memory user cache.
Using shared memory instead of the default file session storage helps improve performance of PHP applications
that store large amount of data in session objects.
</para>
<para>
To configure PHP to use WinCache session handler set the <filename>php.ini</filename> setting
<link linkend="ini.session.save-handler">session.save_handler</link> to <emphasis>wincache</emphasis>.
<example>
<title>Enabling WinCache session handler</title>
<programlisting role="php">
<![CDATA[
session.save_handler = wincache
]]>
</programlisting>
</example>
<note>
<simpara>
In beta release of WinCache Extension 1.1, the user cache is kept in memory and is not backed by a
file system storage. This means that the session data stored in the shared memory will be lost when
IIS application pool is recycled.
</simpara>
</note>
</para>
</section>
<section xml:id="wincache.resources">
&reftitle.resources;

View file

@ -20,6 +20,8 @@
<function name='wincache_ucache_inc' from='PECL wincache &gt;= 1.1.0'/>
<function name='wincache_ucache_dec' from='PECL wincache &gt;= 1.1.0'/>
<function name='wincache_ucache_cas' from='PECL wincache &gt;= 1.1.0'/>
<function name='wincache_ucache_info' from='PECL wincache &gt;= 1.1.0'/>
<function name='wincache_ucache_meminfo' from='PECL wincache &gt;= 1.1.0'/>
</versions>
<!-- Keep this comment at the end of the file