Adding documentation for WinCache 1.1.0 release. Documenting the user cache API's.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@295766 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ruslan Yakushev 2010-03-03 01:43:44 +00:00
parent fbdf7f9578
commit 811f955757
10 changed files with 1217 additions and 0 deletions

View file

@ -0,0 +1,174 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 290998 $ -->
<refentry xml:id="function.wincache-ucache-add" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_add</refname>
<refpurpose>
Adds a variable in user cache only if variable does not already exist in the cache
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>wincache_ucache_add</methodname>
<methodparam><type>mixed</type><parameter>key</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<para>
Adds a variable in user cache, only if this variable doesn't already exist in the cache.
The added variable remains in the user cache unless its time to live expires or it is
deleted by using <function>wincache_ucache_delete</function> or <function>wincache_ucache_clear</function> functions.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>key</parameter></term>
<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
<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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
Value of a variable to store. <parameter>Value</parameter> supports all data types except resources, such as file handles.
This paramter is ignored if first argument is an array. A general guidance is to pass <literal>NULL</literal>
as <parameter>value</parameter> while using array as <parameter>key</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ttl</parameter></term>
<listitem>
<para>
Time for the variable to live in the cache in seconds. After the value specified in <parameter>ttl</parameter> has passed
the stored variable will be deleted from the cache. This parameter takes a default value of <literal>0</literal> which means
the variable will stay in the cache unless explicitly deleted by using <function>wincache_ucache_delete</function>
or <function>wincache_ucache_clear</function> functions.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
If <parameter>key</parameter> is string, the function returns <literal>TRUE</literal> on success and <literal>FALSE</literal> on failure.
</simpara>
<para>
If <parameter>key</parameter> is an array, the function returns:
<itemizedlist spacing="compact">
<listitem>
<simpara>
If all the name => value pairs in the array can be set, function returns an empty array;
</simpara>
</listitem>
<listitem>
<simpara>
If all the name => value pairs in the array cannot be set, function returns <literal>FALSE</literal>;
</simpara>
</listitem>
<listitem>
<simpara>
If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache.
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>wincache_ucache_add</function> with <parameter>key</parameter> as a string</title>
<programlisting role="php">
<![CDATA[
<?php
$bar = 'BAR';
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_get('foo'));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
bool(true)
bool(false)
string(3) "BAR"
]]>
</screen>
</example>
</para>
<para>
<example>
<title><function>wincache_ucache_add</function> with <parameter>key</parameter> as an array</title>
<programlisting role="php">
<![CDATA[
<?php
$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'));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(0) {}
bool(false)
string(1) "6"
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_ucache_set</function></member>
<member><function>wincache_ucache_get</function></member>
<member><function>wincache_ucache_delete</function></member>
<member><function>wincache_ucache_clear</function></member>
<member><function>wincache_ucache_exists</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

@ -0,0 +1,121 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 290998 $ -->
<refentry xml:id="function.wincache-ucache-cas" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_cas</refname>
<refpurpose>
Compares the variable with old value and assigns new value to it
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>wincache_ucache_cas</methodname>
<methodparam><type>string</type><parameter>key</parameter></methodparam>
<methodparam><type>long</type><parameter>old_value</parameter></methodparam>
<methodparam><type>long</type><parameter>new_value</parameter></methodparam>
</methodsynopsis>
<para>
Compares the variable associated with the <parameter>key</parameter> with <parameter>old_value</parameter>
and if it matches then assigns the <parameter>new_value</parameter> to it.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
The <parameter>key</parameter> that is used to store the variable in the cache.
<parameter>key</parameter> is case sensitive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>old_value</parameter></term>
<listitem>
<para>
Old value of the variable pointed by <parameter>key</parameter> in the user cache.
The value should be of type <literal>long</literal>, otherwise the function returns
<literal>FALSE</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>new_value</parameter></term>
<listitem>
<para>
New value which will get assigned to variable pointer by <parameter>key</parameter> if a
match is found. The value should be of type <literal>long</literal>, otherwise
the function returns <literal>FALSE</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Using <function>wincache_ucache_cas</function></title>
<programlisting role="php">
<![CDATA[
<?php
wincache_ucache_set('counter', 2922);
var_dump(wincache_ucache_cas('counter', 2922, 1));
var_dump(wincache_ucache_get('counter'));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
bool(true)
int(1)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_ucache_inc</function></member>
<member><function>wincache_ucache_dec</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

@ -0,0 +1,96 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 290998 $ -->
<refentry xml:id="function.wincache-ucache-clear" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_clear</refname>
<refpurpose>
Deletes entire content of the user cache
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>wincache_ucache_clear</methodname>
<void/>
</methodsynopsis>
<para>
Clears/deletes all the values stored in the user cache.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>using <function>wincache_ucache_clear</function></title>
<programlisting role="php">
<![CDATA[
<?php
wincache_ucache_set('green', 1);
wincache_ucache_set('red', 2);
wincache_ucache_set('orange', 4);
wincache_ucache_set('blue', 8);
wincache_ucache_set('cyan', 16);
$array1 = array('green', 'red', 'orange', 'blue', 'cyan');
var_dump(wincache_ucache_get($array1));
var_dump(wincache_ucache_clear());
var_dump(wincache_ucache_get($array1));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(5) { ["green"]=> int(1)
["red"]=> int(2)
["orange"]=> int(4)
["blue"]=> int(8)
["cyan"]=> int(16) }
bool(true)
bool(false)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_ucache_set</function></member>
<member><function>wincache_ucache_add</function></member>
<member><function>wincache_ucache_delete</function></member>
<member><function>wincache_ucache_get</function></member>
<member><function>wincache_ucache_exists</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

@ -0,0 +1,120 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 290998 $ -->
<refentry xml:id="function.wincache-ucache-dec" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_dec</refname>
<refpurpose>
Decrements the value associated with the key
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>wincache_ucache_dec</methodname>
<methodparam><type>string</type><parameter>key</parameter></methodparam>
<methodparam choice="opt"><type>long</type><parameter>dec_by</parameter><initializer>1</initializer></methodparam>
<methodparam choice="opt"><type>bool</type><parameter role="reference">success</parameter></methodparam>
</methodsynopsis>
<para>
Decrements the value associated with the <parameter>key</parameter> by 1 or as specified
by <parameter>dec_by</parameter>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
The <parameter>key</parameter> that was used to store the variable in the cache.
<parameter>key</parameter> is case sensitive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dec_by</parameter></term>
<listitem>
<para>
The value by which the variable associated with the <parameter>key</parameter> will get decremented.
If the argument is a floating point number it will be truncated to nearest integer. The variable
associated with the <parameter>key</parameter> should be of type <literal>long</literal>, otherwise
the function fails and returns <literal>FALSE</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>success</parameter></term>
<listitem>
<para>
Will be set to <literal>TRUE</literal> on success and <literal>FALSE</literal> on failure.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
Returns the decremented value on success and <literal>FALSE</literal> on failure.
</simpara>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Using <function>wincache_ucache_dec</function></title>
<programlisting role="php">
<![CDATA[
<?php
wincache_ucache_set('counter', 1);
var_dump(wincache_ucache_dec('counter', 2923, $success));
var_dump($success);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
int(2922)
bool(true)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_ucache_inc</function></member>
<member><function>wincache_ucache_cas</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

@ -0,0 +1,152 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 290998 $ -->
<refentry xml:id="function.wincache-ucache-delete" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_delete</refname>
<refpurpose>
Deletes variables from the user cache
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>wincache_ucache_delete</methodname>
<methodparam><type>mixed</type><parameter>key</parameter></methodparam>
</methodsynopsis>
<para>
Deletes the elements in the user cache pointed by <parameter>key</parameter>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
The <parameter>key</parameter> that was used to store the variable in the cache.
<parameter>key</parameter> is case sensitive. <parameter>key</parameter> can be an
array of keys.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
<para>
If <parameter>key</parameter> is an array then the function returns <literal>FALSE</literal>
if every element of the array fails to get deleted from the user cache, otherwise returns an
array which consists of all the keys that are deleted.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Using <function>wincache_ucache_delete</function> with <parameter>key</parameter> as a string</title>
<programlisting role="php">
<![CDATA[
<?php
wincache_ucache_set('foo', 'bar');
var_dump(wincache_ucache_delete('foo'));
var_dump(wincache_ucache_exists('foo'));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
bool(true)
bool(false)
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Using<function>wincache_ucache_delete</function> with <parameter>key</parameter> as an array</title>
<programlisting role="php">
<![CDATA[
<?php
$array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('green', 'blue', 'yellow', 'cyan');
var_dump(wincache_ucache_delete($array2));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(4) { [0]=> string(5) "green"
[1]=> string(4) "Blue"
[2]=> string(6) "yellow"
[3]=> string(4) "cyan" }
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Using <function>wincache_ucache_delete</function> with <parameter>key</parameter> as an array where some elements cannot be deleted</title>
<programlisting role="php">
<![CDATA[
<?php
$array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('orange', 'red', 'yellow', 'cyan');
var_dump(wincache_ucache_delete($array2));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(2) { [0]=> string(6) "yellow"
[1]=> string(4) "cyan" }
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_ucache_set</function></member>
<member><function>wincache_ucache_add</function></member>
<member><function>wincache_ucache_get</function></member>
<member><function>wincache_ucache_clear</function></member>
<member><function>wincache_ucache_exists</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

@ -0,0 +1,100 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 290998 $ -->
<refentry xml:id="function.wincache-ucache-exists" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_exists</refname>
<refpurpose>
Checks if a variable exists in the user cache
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>wincache_ucache_exists</methodname>
<methodparam><type>string</type><parameter>key</parameter></methodparam>
</methodsynopsis>
<para>
Checks if a variable with the <parameter>key</parameter> exists in the user cache or not.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
The <parameter>key</parameter> that was used to store the variable in the cache.
<parameter>key</parameter> is case sensitive.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns <literal>TRUE</literal> if variable with the <parameter>key</parameter> exitsts,
otherwise returns <literal>FALSE</literal>.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Using <function>wincache_ucache_exists</function></title>
<programlisting role="php">
<![CDATA[
<?php
if (!wincache_ucache_exists('green'))
wincache_ucache_set('green', 1);
var_dump(wincache_ucache_exists('green'));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
bool(true)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_ucache_set</function></member>
<member><function>wincache_ucache_add</function></member>
<member><function>wincache_ucache_get</function></member>
<member><function>wincache_ucache_clear</function></member>
<member><function>wincache_ucache_delete</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

@ -0,0 +1,147 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 290998 $ -->
<refentry xml:id="function.wincache-ucache-get" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_get</refname>
<refpurpose>
Gets a variable stored in the user cache
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>wincache_ucache_get</methodname>
<methodparam><type>mixed</type><parameter>key</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter role="reference">success</parameter></methodparam>
</methodsynopsis>
<para>
Gets a variable stored in the user cache.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
The <parameter>key</parameter> that was used to store the variable in the cache.
<parameter>key</parameter> is case sensitive. <parameter>key</parameter> can be an
array of keys. In this case the return value will be an array of values of each element
in the <parameter>key</parameter> array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>success</parameter></term>
<listitem>
<para>
Will be set to <literal>TRUE</literal> on success and <literal>FALSE</literal> on failure.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
If <parameter>key</parameter> is a string, the function returns the value of the variable stored with that key.
The <parameter>success</parameter> is set to <literal>TRUE</literal> on success and
to <literal>FALSE</literal> on failure.
</simpara>
<simpara>
The <parameter>key</parameter> is an array, the parameter <parameter>success</parameter>
is always set to <literal>TRUE</literal>. The returned array (name => value pairs) will
contain only those name => value pairs for which the get operation in user cache was
successful. If none of the keys in the key array finds a match in the user cache
an empty array will be returned.
</simpara>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>wincache_ucache_get</function> with <parameter>key</parameter> as a string</title>
<programlisting role="php">
<![CDATA[
<?php
wincache_ucache_add('color', 'blue');
var_dump(wincache_ucache_get('color', $success));
var_dump($success);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(4) "blue"
bool(true)
]]>
</screen>
</example>
</para>
<para>
<example>
<title><function>wincache_ucache_get</function> with <parameter>key</parameter> as an array</title>
<programlisting role="php">
<![CDATA[
<?php
$array1 = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('green', 'Blue', 'yellow', 'cyan');
var_dump(wincache_ucache_get($array2, $success));
var_dump($success);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(4) { ["green"]=> string(1) "5"
["Blue"]=> string(1) "6"
["yellow"]=> string(1) "7"
["cyan"]=> string(1) "8" }
bool(true)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_ucache_add</function></member>
<member><function>wincache_ucache_set</function></member>
<member><function>wincache_ucache_delete</function></member>
<member><function>wincache_ucache_clear</function></member>
<member><function>wincache_ucache_exists</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

@ -0,0 +1,120 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 290998 $ -->
<refentry xml:id="function.wincache-ucache-inc" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_inc</refname>
<refpurpose>
Increments the value associated with the key
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>wincache_ucache_inc</methodname>
<methodparam><type>string</type><parameter>key</parameter></methodparam>
<methodparam choice="opt"><type>long</type><parameter>inc_by</parameter><initializer>1</initializer></methodparam>
<methodparam choice="opt"><type>bool</type><parameter role="reference">success</parameter></methodparam>
</methodsynopsis>
<para>
Increments the value associated with the <parameter>key</parameter> by 1 or as specified
by <parameter>inc_by</parameter>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
The <parameter>key</parameter> that was used to store the variable in the cache.
<parameter>key</parameter> is case sensitive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>inc_by</parameter></term>
<listitem>
<para>
The value by which the variable associated with the <parameter>key</parameter> will get incremented.
If the argument is a floating point number it will be truncated to nearest integer. The variable
associated with the <parameter>key</parameter> should be of type <literal>long</literal>, otherwise
the function fails and returns <literal>FALSE</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>success</parameter></term>
<listitem>
<para>
Will be set to <literal>TRUE</literal> on success and <literal>FALSE</literal> on failure.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
Returns the incremented value on success and <literal>FALSE</literal> on failure.
</simpara>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Using <function>wincache_ucache_inc</function></title>
<programlisting role="php">
<![CDATA[
<?php
wincache_ucache_set('counter', 1);
var_dump(wincache_ucache_inc('counter', 2921, $success));
var_dump($success);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
int(2922)
bool(true)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_ucache_dec</function></member>
<member><function>wincache_ucache_cas</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

@ -0,0 +1,178 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 290998 $ -->
<refentry xml:id="function.wincache-ucache-set" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>wincache_ucache_set</refname>
<refpurpose>
Adds a variable in user cache and overwrites a variable if it already exists in the cache
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>wincache_ucache_set</methodname>
<methodparam><type>mixed</type><parameter>key</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<para>
Adds a variable in user cache. Overwrites a variable if it already exists in the cache.
The added or updated variable remains in the user cache unless its time to live expires or it is
deleted by using <function>wincache_ucache_delete</function> or <function>wincache_ucache_clear</function> functions.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
Store the variable using this <parameter>key</parameter> name. If a variable with same
<parameter>key</parameter> is already present the function will overwrite the previous
value with the new one. <parameter>key</parameter> is case sensitive.
<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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
Value of a variable to store. <parameter>Value</parameter> supports all data types except resources, such as file handles.
This paramter is ignored if first argument is an array. A general guidance is to pass <literal>NULL</literal>
as <parameter>value</parameter> while using array as <parameter>key</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ttl</parameter></term>
<listitem>
<para>
Time for the variable to live in the cache in seconds. After the value specified in <parameter>ttl</parameter> has passed
the stored variable will be deleted from the cache. This parameter takes a default value of <literal>0</literal> which means
the variable will stay in the cache unless explicitly deleted by using <function>wincache_ucache_delete</function>
or <function>wincache_ucache_clear</function> functions.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
If <parameter>key</parameter> is string, the function returns <literal>TRUE</literal> on success and <literal>FALSE</literal> on failure.
</simpara>
<para>
If <parameter>key</parameter> is an array, the function returns:
<itemizedlist spacing="compact">
<listitem>
<simpara>
If all the name => value pairs in the array can be set, function returns an empty array;
</simpara>
</listitem>
<listitem>
<simpara>
If all the name => value pairs in the array cannot be set, function returns <literal>FALSE</literal>;
</simpara>
</listitem>
<listitem>
<simpara>
If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache.
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>wincache_ucache_set</function> with <parameter>key</parameter> as a string</title>
<programlisting role="php">
<![CDATA[
<?php
$bar = 'BAR';
var_dump(wincache_ucache_set('foo', $bar));
var_dump(wincache_ucache_get('foo'));
$bar1 = 'BAR1'
var_dump(wincache_ucache_set('foo', $bar1));
var_dump(wincache_ucache_get('foo'));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
bool(true)
string(3) "BAR"
bool(true)
string(3) "BAR1"
]]>
</screen>
</example>
</para>
<para>
<example>
<title><function>wincache_ucache_set</function> with <parameter>key</parameter> as an array</title>
<programlisting role="php">
<![CDATA[
<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(0) {}
array(0) {}
string(1) "6"
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>wincache_ucache_add</function></member>
<member><function>wincache_ucache_get</function></member>
<member><function>wincache_ucache_delete</function></member>
<member><function>wincache_ucache_clear</function></member>
<member><function>wincache_ucache_exists</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

@ -11,6 +11,15 @@
<function name='wincache_rplist_fileinfo' from='PECL wincache &gt;= 1.0.0'/>
<function name='wincache_rplist_meminfo' from='PECL wincache &gt;= 1.0.0'/>
<function name='wincache_refresh_if_changed' from='PECL wincache &gt;= 1.0.0'/>
<function name='wincache_ucache_add' from='PECL wincache &gt;= 1.1.0'/>
<function name='wincache_ucache_set' from='PECL wincache &gt;= 1.1.0'/>
<function name='wincache_ucache_get' from='PECL wincache &gt;= 1.1.0'/>
<function name='wincache_ucache_clear' from='PECL wincache &gt;= 1.1.0'/>
<function name='wincache_ucache_delete' from='PECL wincache &gt;= 1.1.0'/>
<function name='wincache_ucache_exists' from='PECL wincache &gt;= 1.1.0'/>
<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'/>
</versions>
<!-- Keep this comment at the end of the file