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

Fixing indentation - I told NetBeans to use single space

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@301137 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ulf Wendel 2010-07-09 16:02:41 +00:00
parent 2cdfda0553
commit d9e565cad1
13 changed files with 1770 additions and 1762 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

416
reference/mysqlnd_qc/book.xml
View file

@ -3,229 +3,229 @@
<!-- Membership: pecl -->
<book xml:id="book.mysqlnd-qc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Mysqlnd query result cache plugin</title>
<titleabbrev>mysqlnd_qc</titleabbrev>
<title>Mysqlnd query result cache plugin</title>
<titleabbrev>mysqlnd_qc</titleabbrev>
<preface xml:id="intro.mysqlnd-qc">
<preface xml:id="intro.mysqlnd-qc">
&reftitle.intro;
<para>
The mysqlnd query result cache plugin adds easy to use client-side query
caching to all PHP MySQL extensions using
<link linkend="book.mysqlnd">mysqlnd</link>.
</para>
<para>
As of version PHP 5.3.3 the MySQL native driver for PHP (
<literal>mysqlnd</literal>)
features an internal plugin C API. C plugins, such as the query cache
plugin, can extend the functionality of
<link linkend="book.mysqlnd">mysqlnd</link>.
</para>
<para>
The MySQL native driver for PHP is a C library which ships together with
PHP as of PHP 5.3.0. It serves as a drop-in replacement for the
MySQL Client Library (AKA libmysql/libmysqlclient). Using mysqlnd has
several advantages: no extra downloads because it comes with PHP,
PHP license, lower memory consumption in certain cases,
new functionality such as asynchronous queries.
</para>
<para>
Mysqlnd plugins such as the query cache plugin operate transparent
from a user perspective. The cache plugin supports all PHP applications
and all PHP MySQL extensions (
<link linkend="ref.mysqli">mysqli</link>,
<link linkend="ref.mysql">mysql</link>,
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>).
It does not change existing APIs.
</para>
<para>
No significant application changes are required to cache a query.
The cache has two operation modes. It will either cache all
queries (not recommended) or only those queries marked with a
certain SQL hint (recommended).
</para>
<para>
The mysqlnd query result cache plugin adds easy to use client-side query
caching to all PHP MySQL extensions using
<link linkend="book.mysqlnd">mysqlnd</link>.
</para>
<para>
As of version PHP 5.3.3 the MySQL native driver for PHP (
<literal>mysqlnd</literal>)
features an internal plugin C API. C plugins, such as the query cache
plugin, can extend the functionality of
<link linkend="book.mysqlnd">mysqlnd</link>.
</para>
<para>
The MySQL native driver for PHP is a C library which ships together with
PHP as of PHP 5.3.0. It serves as a drop-in replacement for the
MySQL Client Library (AKA libmysql/libmysqlclient). Using mysqlnd has
several advantages: no extra downloads because it comes with PHP,
PHP license, lower memory consumption in certain cases,
new functionality such as asynchronous queries.
</para>
<para>
Mysqlnd plugins such as the query cache plugin operate transparent
from a user perspective. The cache plugin supports all PHP applications
and all PHP MySQL extensions (
<link linkend="ref.mysqli">mysqli</link>,
<link linkend="ref.mysql">mysql</link>,
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>).
It does not change existing APIs.
</para>
<para>
No significant application changes are required to cache a query.
The cache has two operation modes. It will either cache all
queries (not recommended) or only those queries marked with a
certain SQL hint (recommended).
</para>
<section xml:id="mysqlnd-qc.key_features">
<title>Key Features</title>
<section xml:id="mysqlnd-qc.key_features">
<title>Key Features</title>
<para>
<itemizedlist>
<listitem>
<para>
<itemizedlist>
<listitem>
<para>
Transparent and therefore easy to use
</para>
<para>
<itemizedlist>
<listitem>
<para>
supports all PHP MySQL extensions
</para>
</listitem>
<listitem>
<para>
no API changes
</para>
</listitem>
<listitem>
<para>
very little application changes required
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
Transparent and therefore easy to use
</para>
<para>
<itemizedlist>
<listitem>
<para>
supports all PHP MySQL extensions
</para>
</listitem>
<listitem>
<para>
no API changes
</para>
</listitem>
<listitem>
<para>
very little application changes required
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
Flexible invalidation strategy
</para>
<para>
<itemizedlist>
<listitem>
<para>
Time-to-Live (TTL)
</para>
</listitem>
<listitem>
<para>
user-defined
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
Flexible invalidation strategy
</para>
<para>
<itemizedlist>
<listitem>
<para>
Time-to-Live (TTL)
</para>
</listitem>
<listitem>
<para>
user-defined
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
Storage with different scope and life-span
</para>
<para>
<itemizedlist>
<listitem>
<para>
Default (Hash)
</para>
</listitem>
<listitem>
<para>
<link linkend="ref.apc">APC</link>
</para>
</listitem>
<listitem>
<para>
MEMCACHE
</para>
</listitem>
<listitem>
<para>
sqlite
</para>
</listitem>
<listitem>
<para>
user-defined
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
<listitem>
<para>
Storage with different scope and life-span
</para>
</section>
<para>
<itemizedlist>
<listitem>
<para>
Default (Hash)
</para>
</listitem>
<listitem>
<para>
<link linkend="ref.apc">APC</link>
</para>
</listitem>
<listitem>
<para>
MEMCACHE
</para>
</listitem>
<listitem>
<para>
sqlite
</para>
</listitem>
<listitem>
<para>
user-defined
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section xml:id="mysqlnd-qc.limitations">
<title>Limitations</title>
<section xml:id="mysqlnd-qc.limitations">
<title>Limitations</title>
<para>
The query cache plugin prototype will not cache unbuffered
queries or results from prepared statements. This limitation
is likely to be lifted soon.
</para>
<para>
The following popular user API calls use buffered queries which
can be cached:
</para>
<para>
<itemizedlist>
<listitem>
<para>
The query cache plugin prototype will not cache unbuffered
queries or results from prepared statements. This limitation
is likely to be lifted soon.
<link linkend="ref.mysqli">mysqli</link>
<itemizedlist>
<listitem>
<para>
<function>mysqli_query</function>
</para>
</listitem>
<listitem>
<para>
<function>mysqli_real_query</function> +
<function>mysqli_store_result</function>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
The following popular user API calls use buffered queries which
can be cached:
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>
<itemizedlist>
<listitem>
<para>
<function>PDO::query</function> if
<literal>PDO::ATTR_EMULATE_PREPARES = 1</literal> (default setting)
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<itemizedlist>
<listitem>
<para>
<link linkend="ref.mysqli">mysqli</link>
<itemizedlist>
<listitem>
<para>
<function>mysqli_query</function>
</para>
</listitem>
<listitem>
<para>
<function>mysqli_real_query</function> +
<function>mysqli_store_result</function>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>
<itemizedlist>
<listitem>
<para>
<function>PDO::query</function> if
<literal>PDO::ATTR_EMULATE_PREPARES = 1</literal> (default setting)
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<link linkend="ref.mysql">mysql</link>
<itemizedlist>
<listitem>
<para>
<function>mysql_query</function>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
<link linkend="ref.mysql">mysql</link>
<itemizedlist>
<listitem>
<para>
<function>mysql_query</function>
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section xml:id="mysqlnd-qc.architecture">
<title>Architecture</title>
<para>
The query cache is implemented as a PHP extension.
It is written in C and operates under the hood of PHP. During the
startup of the PHP interpreter it gets registered as a
<link linkend="book.mysqlnd">mysqlnd</link> plugin to replace selected
mysqlnd C methods.
</para>
<para>
At PHP run time it proxies queries send from
mysqlnd (PHP) to the MySQL server. If a query string starts with the SQL hint
(
<literal>/*qc=on*/</literal>) to enable caching of it and the query
is not cached (cache miss), the query cache plugin will record the
raw wire protocol data send from MySQL to PHP to answer the query.
The query cache records the wire protocol data in its cache
and replays it, if still valid, on a cache hit.
</para>
<para>
Note that the query cache does not hold decoded result sets consisting
of
<literal>zvals</literal> (C struct representing a PHP variable).
It stores the raw wire data of the MySQL client server protocol.
In case of a cache hits,
<link linkend="book.mysqlnd">mysqlnd</link> still needs
to decode the cached raw wire data into PHP variables before passing
the result to the user space.
This approach has one major advantage: simplicity. Furthermore this
approach eliminates the need for serializing data for cache storage.
</para>
</section>
</preface>
</listitem>
</itemizedlist>
</para>
</section>
<section xml:id="mysqlnd-qc.architecture">
<title>Architecture</title>
<para>
The query cache is implemented as a PHP extension.
It is written in C and operates under the hood of PHP. During the
startup of the PHP interpreter it gets registered as a
<link linkend="book.mysqlnd">mysqlnd</link> plugin to replace selected
mysqlnd C methods.
</para>
<para>
At PHP run time it proxies queries send from
mysqlnd (PHP) to the MySQL server. If a query string starts with the SQL hint
(
<literal>/*qc=on*/</literal>) to enable caching of it and the query
is not cached (cache miss), the query cache plugin will record the
raw wire protocol data send from MySQL to PHP to answer the query.
The query cache records the wire protocol data in its cache
and replays it, if still valid, on a cache hit.
</para>
<para>
Note that the query cache does not hold decoded result sets consisting
of
<literal>zvals</literal> (C struct representing a PHP variable).
It stores the raw wire data of the MySQL client server protocol.
In case of a cache hits,
<link linkend="book.mysqlnd">mysqlnd</link> still needs
to decode the cached raw wire data into PHP variables before passing
the result to the user space.
This approach has one major advantage: simplicity. Furthermore this
approach eliminates the need for serializing data for cache storage.
</para>
</section>
</preface>
&reference.mysqlnd-qc.setup;

18
reference/mysqlnd_qc/configure.xml
View file

@ -3,18 +3,18 @@
<section xml:id="mysqlnd-qc.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.install;
<para>
&pecl.moved;
</para>
<para>
&pecl.moved;
</para>
<para>
<para>
&pecl.info;
<link xlink:href="&url.pecl.package;mysqlnd_qc">&url.pecl.package;mysqlnd_qc</link>
</para>
<link xlink:href="&url.pecl.package;mysqlnd_qc">&url.pecl.package;mysqlnd_qc</link>
</para>
<para>
&pecl.windows.download;
</para>
<para>
&pecl.windows.download;
</para>
</section>

124
reference/mysqlnd_qc/constants.xml
View file

@ -4,25 +4,25 @@
<appendix xml:id="mysqlnd-qc.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.constants;
&extension.constants;
<para>
<emphasis role="bold">SQL hint related</emphasis>
</para>
<para>
<example>
<para>
The query cache is controled by SQL hints. SQL hints are used to enable and
disable caching. SQL hints can be used to set the
<literal>TTL</literal> of a query.
</para>
<para>
The SQL hints recognized by the query cache can be manually changed at
compile time. This makes it possible to use
<literal>mysqlnd_qc</literal> in environments in which the default
SQL hints are already taken and interpreted by other systems. Therefore
it is recommended to use the SQL hint string constants instead of
manually adding the default SQL hints to the query string.
</para>
<programlisting role="php">
<para>
<emphasis role="bold">SQL hint related</emphasis>
</para>
<para>
<example>
<para>
The query cache is controled by SQL hints. SQL hints are used to enable and
disable caching. SQL hints can be used to set the
<literal>TTL</literal> of a query.
</para>
<para>
The SQL hints recognized by the query cache can be manually changed at
compile time. This makes it possible to use
<literal>mysqlnd_qc</literal> in environments in which the default
SQL hints are already taken and interpreted by other systems. Therefore
it is recommended to use the SQL hint string constants instead of
manually adding the default SQL hints to the query string.
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Use constants for maximum portability */
@ -39,62 +39,62 @@ printf("MYSQLND_QC_DISABLE_SWITCH: %s\n", MYSQLND_QC_DISABLE_SWITCH);
printf("MYSQLND_QC_TTL_SWITCH: %s\n", MYSQLND_QC_TTL_SWITCH);
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
MYSQLND_QC_ENABLE_SWITCH: qc=on
MYSQLND_QC_DISABLE_SWITCH: qc=off
MYSQLND_QC_TTL_SWITCH: qc_ttl=
]]>
</screen>
</screen>
</example>
</para>
</example>
</para>
<para>
<variablelist>
<varlistentry>
<term>
<constant>MYSQLND_QC_ENABLE_SWITCH</constant>
<para>
<variablelist>
<varlistentry>
<term>
<constant>MYSQLND_QC_ENABLE_SWITCH</constant>
(
<type>string</type>)
</term>
<listitem>
<simpara>
<type>string</type>)
</term>
<listitem>
<simpara>
SQL hint used to enable caching of a query.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>MYSQLND_QC_DISABLE_SWITCH</constant>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>MYSQLND_QC_DISABLE_SWITCH</constant>
(
<type>string</type>)
</term>
<listitem>
<simpara>
SQL hint used to disable caching of a query if
<literal>mysqlnd_qc.cache_by_default = 1</literal>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>MYSQLND_QC_TTL_SWITCH</constant>
<type>string</type>)
</term>
<listitem>
<simpara>
SQL hint used to disable caching of a query if
<literal>mysqlnd_qc.cache_by_default = 1</literal>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>MYSQLND_QC_TTL_SWITCH</constant>
(
<type>string</type>)
</term>
<listitem>
<simpara>
SQL hint used to set the TTL of a result set.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<type>string</type>)
</term>
<listitem>
<simpara>
SQL hint used to set the TTL of a result set.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</appendix>

157
reference/mysqlnd_qc/functions/mysqlnd-qc-change-handler.xml
View file

@ -2,76 +2,77 @@
<!-- $Revision$ -->
<refentry xml:id="function.mysqlnd_qc_change_handler" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_qc_change_handler</refname>
<refpurpose>Change current storage handler</refpurpose>
</refnamediv>
<refnamediv>
<refname>mysqlnd_qc_change_handler</refname>
<refpurpose>Change current storage handler</refpurpose>
</refnamediv>
<refsect1 role="description">
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type>
<methodname>mysqlnd_qc_change_handler</methodname>
<methodparam>
<type>mixed</type>
<parameter>handler</parameter>
</methodparam>
</methodsynopsis>
<para>
Sets the storage handler used by the query cache. A list of available
storage handler can be obtained from <function>mysqlnd_qc_get_handler</function>.
Which storage are available depends on the compile time
configuration of the query cache plugin. The
<literal>default</literal> storage handler is always available.
All other storage handler must be enabled explicitly when building the
extension.
</para>
<methodsynopsis>
<type>bool</type>
<methodname>mysqlnd_qc_change_handler</methodname>
<methodparam>
<type>mixed</type>
<parameter>handler</parameter>
</methodparam>
</methodsynopsis>
<para>
Sets the storage handler used by the query cache. A list of available
storage handler can be obtained from
<function>mysqlnd_qc_get_handler</function>.
Which storage are available depends on the compile time
configuration of the query cache plugin. The
<literal>default</literal> storage handler is always available.
All other storage handler must be enabled explicitly when building the
extension.
</para>
</refsect1>
</refsect1>
<refsect1 role="parameters">
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term>
<parameter>handler</parameter>
</term>
<listitem>
<para>
Handler can be of type string representing the name of a
built-in storage handler or an object of type
<literal>mysqlnd_qc_handler_default</literal>.
The names of the built-in storage handler are
<literal>default</literal>,
<literal>APC</literal>,
<literal>MEMCACHE</literal>,
<literal>sqlite</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<variablelist>
<varlistentry>
<term>
<parameter>handler</parameter>
</term>
<listitem>
<para>
Handler can be of type string representing the name of a
built-in storage handler or an object of type
<literal>mysqlnd_qc_handler_default</literal>.
The names of the built-in storage handler are
<literal>default</literal>,
<literal>APC</literal>,
<literal>MEMCACHE</literal>,
<literal>sqlite</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<para>
&return.success;
</para>
<para>
If changing the storage handler fails a catchable fatal error will
be thrown. The query cache cannot operate if the previous storage
handler has been shutdown but no new storage handler has been installed.
</para>
</refsect1>
</para>
<para>
If changing the storage handler fails a catchable fatal error will
be thrown. The query cache cannot operate if the previous storage
handler has been shutdown but no new storage handler has been installed.
</para>
</refsect1>
<refsect1 role="examples">
<refsect1 role="examples">
&reftitle.examples;
<example>
<para>
The example shows the output from the built-in default storage handler.
Other storage handler may report different data.
</para>
<programlisting role="php">
<example>
<para>
The example shows the output from the built-in default storage handler.
Other storage handler may report different data.
</para>
<programlisting role="php">
<![CDATA[
<?php
var_dump(mysqlnd_qc_change_handler("memcache"));
@ -83,33 +84,35 @@ if (true === mysqlnd_qc_change_handler("default"))
var_dump(mysqlnd_qc_change_handler("unknown"));
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
bool(true)
Default storage handler activated
Catchable fatal error: mysqlnd_qc_change_handler(): Unknown handler 'unknown' in (file) on line (line)
]]>
</screen>
</screen>
</example>
</refsect1>
</example>
</refsect1>
<refsect1 role="seealso">
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member>
<link linkend="mysqlnd-qc.installation">Installation</link>
</member>
<member>
<link linkend="function.mysqlnd_qc_get_handler"><function>mysqlnd_qc_get_handler</function></link>
</member>
</simplelist>
</para>
</refsect1>
<para>
<simplelist>
<member>
<link linkend="mysqlnd-qc.installation">Installation</link>
</member>
<member>
<link linkend="function.mysqlnd_qc_get_handler">
<function>mysqlnd_qc_get_handler</function>
</link>
</member>
</simplelist>
</para>
</refsect1>
</refentry>

80
reference/mysqlnd_qc/functions/mysqlnd-qc-clear-cache.xml
View file

@ -2,55 +2,55 @@
<!-- $Revision$ -->
<refentry xml:id="function.mysqlnd_qc_clear_cache" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_qc_clear_cache</refname>
<refpurpose>Flush all cache contents</refpurpose>
</refnamediv>
<refnamediv>
<refname>mysqlnd_qc_clear_cache</refname>
<refpurpose>Flush all cache contents</refpurpose>
</refnamediv>
<refsect1 role="description">
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type>
<methodname>mysqlnd_qc_clear_cache</methodname>
<void />
</methodsynopsis>
<para>
Flush all cache contents.
</para>
<para>
Flushing the cache is a storage handler responsibility.
All built-in storage handler but the
<literal>memcache</literal> storage
handler support flushing the cache. The
<literal>memcache</literal>
storage handler cannot flush its cache contents.
</para>
<para>
User-defined storage handler may or may not support the operation.
</para>
<methodsynopsis>
<type>bool</type>
<methodname>mysqlnd_qc_clear_cache</methodname>
<void />
</methodsynopsis>
<para>
Flush all cache contents.
</para>
<para>
Flushing the cache is a storage handler responsibility.
All built-in storage handler but the
<literal>memcache</literal> storage
handler support flushing the cache. The
<literal>memcache</literal>
storage handler cannot flush its cache contents.
</para>
<para>
User-defined storage handler may or may not support the operation.
</para>
</refsect1>
</refsect1>
<refsect1 role="parameters">
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
</refsect1>
<refsect1 role="returnvalues">
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<para>
&return.success;
</para>
<para>
A return value of
<literal>FALSE</literal>
indicates that flushing all cache contents has
failed or the operation is not supported by
the active storage handler. Applications must
not expect that calling the function will always
flush the cache.
</para>
</refsect1>
</para>
<para>
A return value of
<literal>FALSE</literal>
indicates that flushing all cache contents has
failed or the operation is not supported by
the active storage handler. Applications must
not expect that calling the function will always
flush the cache.
</para>
</refsect1>
</refentry>

78
reference/mysqlnd_qc/functions/mysqlnd-qc-get-cache-info.xml
View file

@ -2,49 +2,49 @@
<!-- $Revision$ -->
<refentry xml:id="function.mysqlnd_qc_get_cache_info" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_qc_get_cache_info</refname>
<refpurpose>Returns information on the current handler, the number of cache entries and cache entries, if available</refpurpose>
</refnamediv>
<refnamediv>
<refname>mysqlnd_qc_get_cache_info</refname>
<refpurpose>Returns information on the current handler, the number of cache entries and cache entries, if available</refpurpose>
</refnamediv>
<refsect1 role="description">
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type>
<methodname>mysqlnd_qc_get_cache_info</methodname>
<void />
</methodsynopsis>
<para>
</para>
<methodsynopsis>
<type>array</type>
<methodname>mysqlnd_qc_get_cache_info</methodname>
<void />
</methodsynopsis>
<para>
</refsect1>
</para>
<refsect1 role="parameters">
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
</refsect1>
<refsect1 role="returnvalues">
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns information on the current handler, the number of cache entries and
cache entries, if available. If and what data will be returned for the cache
entries is subject to the active storage handler.
Storage handler are free to return any data. Storage handler are
recommended to return at least the data provided by the default handler,
if technically possible.
</para>
</refsect1>
<refsect1 role="examples">
<para>
Returns information on the current handler, the number of cache entries and
cache entries, if available. If and what data will be returned for the cache
entries is subject to the active storage handler.
Storage handler are free to return any data. Storage handler are
recommended to return at least the data provided by the default handler,
if technically possible.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<para>
The example shows the output from the built-in default storage handler.
Other storage handler may report different data.
</para>
<programlisting role="php">
<example>
<para>
The example shows the output from the built-in default storage handler.
Other storage handler may report different data.
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Populate the cache, e.g. using mysqli */
@ -55,9 +55,9 @@ $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/SELECT id FROM test");
var_dump(mysqlnd_qc_get_cache_info());
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
array(4) {
["num_entries"]=>
@ -122,10 +122,10 @@ array(4) {
}
]]>
</screen>
</screen>
</example>
</refsect1>
</example>
</refsect1>
</refentry>

775
reference/mysqlnd_qc/functions/mysqlnd-qc-get-core-stats.xml
View file

@ -2,385 +2,384 @@
<!-- $Revision$ -->
<refentry xml:id="function.mysqlnd_qc_get_core_stats" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_qc_get_core_stats</refname>
<refpurpose>Statistics collected by the core of the query cache</refpurpose>
</refnamediv>
<refnamediv>
<refname>mysqlnd_qc_get_core_stats</refname>
<refpurpose>Statistics collected by the core of the query cache</refpurpose>
</refnamediv>
<refsect1 role="description">
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type>
<methodname>mysqlnd_qc_get_core_stats</methodname>
<void />
</methodsynopsis>
<para>
Returns an array of statistics collected by the core of the cache plugin.
The same data fields will be reported for any storage handler because the
data is collected by the core.
</para>
<para>
The
<literal>PHP</literal> configuration setting
<literal>mysqlnd_qc.collect_statistics</literal>
controls the collection of statistics. The collection of statistics
is disabled by default for performance reasons.
Disabling the collection of statistics will also disable the collection
of time related statistics.
</para>
<para>
The
<literal>PHP</literal> configuration setting
<literal>mysqlnd_qc.collect_time_statistics</literal> controls the
collection of time related statistics.
</para>
<para>
The scope of the core statistics is the
<literal>PHP</literal> process.
Depending on your deployment model a
<literal>PHP</literal> process may handle one or multiple requests.
</para>
<para>
Statistics are aggregated for all cache entries. It is not possible
to tell how much queries originating from
<literal>mysqli</literal>,
<literal>PDO_MySQL</literal> or
<literal>mysql</literal> API calls have
contributed to the aggregated data values.
</para>
</refsect1>
<methodsynopsis>
<type>array</type>
<methodname>mysqlnd_qc_get_core_stats</methodname>
<void />
</methodsynopsis>
<para>
Returns an array of statistics collected by the core of the cache plugin.
The same data fields will be reported for any storage handler because the
data is collected by the core.
</para>
<para>
The
<literal>PHP</literal> configuration setting
<literal>mysqlnd_qc.collect_statistics</literal>
controls the collection of statistics. The collection of statistics
is disabled by default for performance reasons.
Disabling the collection of statistics will also disable the collection
of time related statistics.
</para>
<para>
The
<literal>PHP</literal> configuration setting
<literal>mysqlnd_qc.collect_time_statistics</literal> controls the
collection of time related statistics.
</para>
<para>
The scope of the core statistics is the
<literal>PHP</literal> process.
Depending on your deployment model a
<literal>PHP</literal> process may handle one or multiple requests.
</para>
<para>
Statistics are aggregated for all cache entries. It is not possible
to tell how much queries originating from
<literal>mysqli</literal>,
<literal>PDO_MySQL</literal> or
<literal>mysql</literal> API calls have
contributed to the aggregated data values.
</para>
</refsect1>
<refsect1 role="parameters">
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
</refsect1>
<refsect1 role="returnvalues">
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<para>
Array of core statistics
</para>
<informaltable>
<tgroup cols="3">
<colspec colwidth="10%"/>
<colspec colwidth="70%"/>
<colspec colwidth="20%"/>
<thead>
<row>
<entry>Statistic</entry>
<entry>Description</entry>
<entry>Version</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<literal>cache_hit</literal>
</entry>
<entry>
Statement is considered cacheable and cached data has been reused.
Statement is considered cacheable and a cache miss happened but
the statement got cached by someone else while we process it and thus
we can fetch the result from the refreshed cache.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>cache_miss</literal>
</entry>
<entry>
Statement is considered cacheable...
<itemizedlist>
<listitem>
<para>
... and has been added to the cache
</para>
</listitem>
<listitem>
<para>
... but the
<literal>PHP</literal>
configuration directive setting of
<literal>mysqlnd_qc.cache_no_table = 1</literal> has prevented
caching.
</para>
</listitem>
<listitem>
<para>
... but an unbuffered result set is requested.
</para>
</listitem>
<listitem>
<para>
... but a buffered result set was empty.
</para>
</listitem>
</itemizedlist>
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>cache_put</literal>
</entry>
<entry>
Statement is considered cacheable and has been added to the cache.
Take care when calculating derived statistics. Storage handler
with a storage life time beyond process scope may report
<literal>cache_put = 0</literal> together with
<literal>cache_hit &gt; 0</literal>, if another process has filled
the cache. You may want to use
<literal>num_entries</literal> from
<function>mysqlnd_qc_get_cache_info</function> if the handler
supports it (
<literal>default</literal>,
<literal>APC</literal>).
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_should_cache</literal>
</entry>
<entry>
Statement is considered cacheable based on query string analysis.
The statement may or may not be added to the cache. See also
<literal>cache_put</literal>.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_should_not_cache</literal>
</entry>
<entry>
Statement is considered not cacheable based on query string analysis.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_not_cached</literal>
</entry>
<entry>
Statement is considered not cacheable or it is
considered cachable but the storage handler has not returned a
hash key for it.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_could_cache</literal>
</entry>
<entry>
Statement is considered cacheable...
<itemizedlist>
<listitem>
<para>
... and statement has been run without errors
</para>
</listitem>
<listitem>
<para>
... and meta data shows at least one column in the result set
</para>
</listitem>
</itemizedlist>
The statement may or may not be in the cache already.
It may or may not be added to the cache later on.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_found_in_cache</literal>
</entry>
<entry>
Statement is considered cacheable and we have found it in the cache
but we have not replayed the cached data yet and we have not send
the result set to the client yet. This is not considered
a cache hit because the client might not fetch the result or
the cached data may be faulty.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_uncached_other</literal>
</entry>
<entry>
Statement is considered cacheable and it may or may not be in
the cache already but either replaying cached data has failed,
no result set is available or some other error has happened.
</entry>
</row>
<row>
<entry>
<literal>query_uncached_no_table</literal>
</entry>
<entry>
Statement has not been cached because the result set has at least
one column which has no table name in its meta data. An example of
such a query is
<literal>SELECT SLEEP(1)</literal>. To cache those
statements you have to change default value of the PHP configuration directive
<literal>mysqlnd_qc.cache_no_table</literal> and set
<literal>mysqlnd_qc.cache_no_table = 1</literal>. Often is is not
desired to cache such statements.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_uncached_use_result</literal>
</entry>
<entry>
Statement would have been cached if a buffered result set
had been used. The situation is also consiered as a cache miss and
<literal>cache_miss</literal> will be incremented as well.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_run_time_cache_hit</literal>
</entry>
<entry>
Aggregated run time (ms) of all cached queries.
Cached queries are those which have incremented
<literal>cache_hit</literal>.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_run_time_cache_put</literal>
</entry>
<entry>
Aggregated run time (ms) of all uncached queries that
have been put into the cache. See also
<literal>cache_put</literal>.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_run_time_total</literal>
</entry>
<entry>
Aggregated run time (ms) of all uncached and cached queries
that have been inspected and executed by the query cache.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_store_time_cache_hit</literal>
</entry>
<entry>
Aggregated store time (ms) of all cached queries.
Cached queries are those which have incremented
<literal>cache_hit</literal>.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_store_time_cache_put</literal>
</entry>
<entry>
Aggregated store time (
<literal>ms</literal>) of all uncached queries that
have been put into the cache. See also
<literal>cache_put</literal>.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_store_time_total</literal>
</entry>
<entry>
Aggregated store time (ms) of all uncached and cached queries
that have been inspected and executed by the query cache.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>receive_bytes_recorded</literal>
</entry>
<entry>
Recorded incoming network traffic (
<literal>bytes</literal>) send from MySQL to PHP.
The traffic may or may not have been added to the cache. The
traffic is the total for all queries regardless if cached or not.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>receive_bytes_replayed</literal>
</entry>
<entry>
Network traffic replayed during cache. This is the total amount of
incoming traffic saved because of the usage of the query cache plugin.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>send_bytes_recorded</literal>
</entry>
<entry>
Recorded outgoing network traffic (
<literal>bytes</literal>) send from MySQL to PHP.
The traffic may or may not have been added to the cache. The
traffic is the total for all queries regardless if cached or not.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>send_bytes_replayed</literal>
</entry>
<entry>
Network traffic replayed during cache. This is the total amount of
outgoing traffic saved because of the usage of the query cache plugin.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>slam_stale_refresh</literal>
</entry>
<entry>
Number of cache misses which triggered serving stale data until
the client causing the cache miss has refreshed the cache entry.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>slam_stale_hit</literal>
</entry>
<entry>
Number of cache hits while a stale cache entry gets refreshed.
</entry>
<entry>Since 1.0.0.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
</para>
<informaltable>
<tgroup cols="3">
<colspec colwidth="10%"/>
<colspec colwidth="70%"/>
<colspec colwidth="20%"/>
<thead>
<row>
<entry>Statistic</entry>
<entry>Description</entry>
<entry>Version</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<literal>cache_hit</literal>
</entry>
<entry>
Statement is considered cacheable and cached data has been reused.
Statement is considered cacheable and a cache miss happened but
the statement got cached by someone else while we process it and thus
we can fetch the result from the refreshed cache.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>cache_miss</literal>
</entry>
<entry>
Statement is considered cacheable...
<itemizedlist>
<listitem>
<para>
... and has been added to the cache
</para>
</listitem>
<listitem>
<para>
... but the
<literal>PHP</literal>
configuration directive setting of
<literal>mysqlnd_qc.cache_no_table = 1</literal> has prevented caching.
</para>
</listitem>
<listitem>
<para>
... but an unbuffered result set is requested.
</para>
</listitem>
<listitem>
<para>
... but a buffered result set was empty.
</para>
</listitem>
</itemizedlist>
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>cache_put</literal>
</entry>
<entry>
Statement is considered cacheable and has been added to the cache.
Take care when calculating derived statistics. Storage handler
with a storage life time beyond process scope may report
<literal>cache_put = 0</literal> together with
<literal>cache_hit &gt; 0</literal>, if another process has filled
the cache. You may want to use
<literal>num_entries</literal> from
<function>mysqlnd_qc_get_cache_info</function> if the handler
supports it (
<literal>default</literal>,
<literal>APC</literal>).
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_should_cache</literal>
</entry>
<entry>
Statement is considered cacheable based on query string analysis.
The statement may or may not be added to the cache. See also
<literal>cache_put</literal>.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_should_not_cache</literal>
</entry>
<entry>
Statement is considered not cacheable based on query string analysis.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_not_cached</literal>
</entry>
<entry>
Statement is considered not cacheable or it is
considered cachable but the storage handler has not returned a
hash key for it.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_could_cache</literal>
</entry>
<entry>
Statement is considered cacheable...
<itemizedlist>
<listitem>
<para>
... and statement has been run without errors
</para>
</listitem>
<listitem>
<para>
... and meta data shows at least one column in the result set
</para>
</listitem>
</itemizedlist>
The statement may or may not be in the cache already.
It may or may not be added to the cache later on.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_found_in_cache</literal>
</entry>
<entry>
Statement is considered cacheable and we have found it in the cache
but we have not replayed the cached data yet and we have not send
the result set to the client yet. This is not considered
a cache hit because the client might not fetch the result or
the cached data may be faulty.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_uncached_other</literal>
</entry>
<entry>
Statement is considered cacheable and it may or may not be in
the cache already but either replaying cached data has failed,
no result set is available or some other error has happened.
</entry>
</row>
<row>
<entry>
<literal>query_uncached_no_table</literal>
</entry>
<entry>
Statement has not been cached because the result set has at least
one column which has no table name in its meta data. An example of
such a query is
<literal>SELECT SLEEP(1)</literal>. To cache those
statements you have to change default value of the PHP configuration directive
<literal>mysqlnd_qc.cache_no_table</literal> and set
<literal>mysqlnd_qc.cache_no_table = 1</literal>. Often is is not
desired to cache such statements.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_uncached_use_result</literal>
</entry>
<entry>
Statement would have been cached if a buffered result set
had been used. The situation is also consiered as a cache miss and
<literal>cache_miss</literal> will be incremented as well.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_run_time_cache_hit</literal>
</entry>
<entry>
Aggregated run time (ms) of all cached queries.
Cached queries are those which have incremented
<literal>cache_hit</literal>.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_run_time_cache_put</literal>
</entry>
<entry>
Aggregated run time (ms) of all uncached queries that
have been put into the cache. See also
<literal>cache_put</literal>.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_run_time_total</literal>
</entry>
<entry>
Aggregated run time (ms) of all uncached and cached queries
that have been inspected and executed by the query cache.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_store_time_cache_hit</literal>
</entry>
<entry>
Aggregated store time (ms) of all cached queries.
Cached queries are those which have incremented
<literal>cache_hit</literal>.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_store_time_cache_put</literal>
</entry>
<entry>
Aggregated store time (
<literal>ms</literal>) of all uncached queries that
have been put into the cache. See also
<literal>cache_put</literal>.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>query_aggr_store_time_total</literal>
</entry>
<entry>
Aggregated store time (ms) of all uncached and cached queries
that have been inspected and executed by the query cache.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>receive_bytes_recorded</literal>
</entry>
<entry>
Recorded incoming network traffic (
<literal>bytes</literal>) send from MySQL to PHP.
The traffic may or may not have been added to the cache. The
traffic is the total for all queries regardless if cached or not.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>receive_bytes_replayed</literal>
</entry>
<entry>
Network traffic replayed during cache. This is the total amount of
incoming traffic saved because of the usage of the query cache plugin.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>send_bytes_recorded</literal>
</entry>
<entry>
Recorded outgoing network traffic (
<literal>bytes</literal>) send from MySQL to PHP.
The traffic may or may not have been added to the cache. The
traffic is the total for all queries regardless if cached or not.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>send_bytes_replayed</literal>
</entry>
<entry>
Network traffic replayed during cache. This is the total amount of
outgoing traffic saved because of the usage of the query cache plugin.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>slam_stale_refresh</literal>
</entry>
<entry>
Number of cache misses which triggered serving stale data until
the client causing the cache miss has refreshed the cache entry.
</entry>
<entry>Since 1.0.0.</entry>
</row>
<row>
<entry>
<literal>slam_stale_hit</literal>
</entry>
<entry>
Number of cache hits while a stale cache entry gets refreshed.
</entry>
<entry>Since 1.0.0.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 role="examples">
<refsect1 role="examples">
&reftitle.examples;
<example>
<programlisting role="php">
<example>
<programlisting role="php">
<![CDATA[
<?php
/* Enable collection of statistics - default: disabled */
@ -402,9 +401,9 @@ $mysqli->query("/*qc=on*/SELECT id FROM test");
var_dump(mysqlnd_qc_get_core_stats());
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
array(26) {
["cache_hit"]=>
@ -462,27 +461,27 @@ array(26) {
}
]]>
</screen>
</screen>
</example>
</refsect1>
</example>
</refsect1>
<refsect1 role="seealso">
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member>
<link linkend="mysqlnd-qc.configuration">Runtime configuration</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.collect-statistics">mysqlnd_qc.collect_statistics</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.time-statistics">mysqlnd_qc.time_statistics</link>
</member>
</simplelist>
</para>
</refsect1>
<para>
<simplelist>
<member>
<link linkend="mysqlnd-qc.configuration">Runtime configuration</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.collect-statistics">mysqlnd_qc.collect_statistics</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.time-statistics">mysqlnd_qc.time_statistics</link>
</member>
</simplelist>
</para>
</refsect1>
</refentry>

96
reference/mysqlnd_qc/functions/mysqlnd-qc-get-handler.xml
View file

@ -2,54 +2,54 @@
<!-- $Revision$ -->
<refentry xml:id="function.mysqlnd_qc_get_handler" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_qc_get_handler</refname>
<refpurpose>Returns a list of available storage handler</refpurpose>
</refnamediv>
<refnamediv>
<refname>mysqlnd_qc_get_handler</refname>
<refpurpose>Returns a list of available storage handler</refpurpose>
</refnamediv>
<refsect1 role="description">
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type>
<methodname>mysqlnd_qc_get_handler</methodname>
<void />
</methodsynopsis>
<para>
Which storage are available depends on the compile time
configuration of the query cache plugin. The
<literal>default</literal> storage handler is always available.
All other storage handler must be enabled explicitly when building the
extension.
</para>
<methodsynopsis>
<type>array</type>
<methodname>mysqlnd_qc_get_handler</methodname>
<void />
</methodsynopsis>
<para>
Which storage are available depends on the compile time
configuration of the query cache plugin. The
<literal>default</literal> storage handler is always available.
All other storage handler must be enabled explicitly when building the
extension.
</para>
</refsect1>
</refsect1>
<refsect1 role="parameters">
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
</refsect1>
<refsect1 role="returnvalues">
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array of available built-in storage handler.
For each storage handler the version number and version string
is given.
</para>
</refsect1>
<para>
Returns an array of available built-in storage handler.
For each storage handler the version number and version string
is given.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<programlisting role="php">
<refsect1 role="examples">
&reftitle.examples;
<example>
<programlisting role="php">
<![CDATA[
<?php
var_dump(mysqlnd_qc_get_handler());
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
array(5) {
["default"]=>
@ -89,24 +89,26 @@ array(5) {
}
}
]]>
</screen>
</screen>
</example>
</refsect1>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member>
<link linkend="mysqlnd-qc.installation">Installation</link>
</member>
<member>
<link linkend="function.mysqlnd_qc_change_handler"><function>mysqlnd_qc_change_handler</function></link>
</member>
</simplelist>
</para>
</refsect1>
<para>
<simplelist>
<member>
<link linkend="mysqlnd-qc.installation">Installation</link>
</member>
<member>
<link linkend="function.mysqlnd_qc_change_handler">
<function>mysqlnd_qc_change_handler</function>
</link>
</member>
</simplelist>
</para>
</refsect1>
</refentry>

322
reference/mysqlnd_qc/functions/mysqlnd-qc-get-query-trace-log.xml
View file

@ -2,155 +2,155 @@
<!-- $Revision$ -->
<refentry xml:id="function.mysqlnd_qc_get_query_trace_log" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_qc_get_query_trace_log</refname>
<refpurpose>Returns a backtrace for each query inspected by the query cache</refpurpose>
</refnamediv>
<refnamediv>
<refname>mysqlnd_qc_get_query_trace_log</refname>
<refpurpose>Returns a backtrace for each query inspected by the query cache</refpurpose>
</refnamediv>
<refsect1 role="description">
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type>
<methodname>mysqlnd_qc_get_query_trace_log</methodname>
<void />
</methodsynopsis>
<para>
Returns a backtrace for each query inspected by the query cache.
The collection of the backtrace is disabled by default. To collect
the backtrace you have to set the PHP configuration directive
<literal>mysqlnd_qc.collect_query_trace</literal> to
<literal>1</literal>
</para>
<para>
The maximum depth of the backtrace is limited to the depth set
with the PHP configuration directive
<literal>mysqlnd_qc.query_trace_bt_depth</literal>.
</para>
<methodsynopsis>
<type>array</type>
<methodname>mysqlnd_qc_get_query_trace_log</methodname>
<void />
</methodsynopsis>
<para>
Returns a backtrace for each query inspected by the query cache.
The collection of the backtrace is disabled by default. To collect
the backtrace you have to set the PHP configuration directive
<literal>mysqlnd_qc.collect_query_trace</literal> to
<literal>1</literal>
</para>
<para>
The maximum depth of the backtrace is limited to the depth set
with the PHP configuration directive
<literal>mysqlnd_qc.query_trace_bt_depth</literal>.
</para>
</refsect1>
</refsect1>
<refsect1 role="parameters">
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
</refsect1>
<refsect1 role="returnvalues">
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
An array of query backtrace. Every list entry contains
the query string, a backtrace and further detail information.
</para>
<para>
An array of query backtrace. Every list entry contains
the query string, a backtrace and further detail information.
</para>
<informaltable>
<tgroup cols="2">
<colspec colwidth="10%"/>
<colspec colwidth="90%"/>
<thead>
<row>
<entry>Key</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<literal>query</literal>
</entry>
<entry>
<informaltable>
<tgroup cols="2">
<colspec colwidth="10%"/>
<colspec colwidth="90%"/>
<thead>
<row>
<entry>Key</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<literal>query</literal>
</entry>
<entry>
Query string.
</entry>
</row>
<row>
<entry>
<literal>origin</literal>
</entry>
<entry>
Code backtrace.
</entry>
</row>
<row>
<entry>
<literal>run_time</literal>
</entry>
<entry>
Query run time in milliseconds. The collection of
of all times and the necessary
<literal>gettimeofday</literal>
system calls can be disabled by setting the PHP configuration
directive
<literal>mysqlnd_qc.time_statistics</literal> to
<literal>0</literal>
</entry>
</row>
<row>
<entry>
<literal>store_time</literal>
</entry>
<entry>
Query result set store time in milliseconds. The collection of
of all times and the necessary
<literal>gettimeofday</literal>
system calls can be disabled by setting the PHP configuration
directive
<literal>mysqlnd_qc.time_statistics</literal> to
<literal>0</literal>
</entry>
</row>
<row>
<entry>
<literal>eligible_for_caching</literal>
</entry>
<entry>
<literal>TRUE</literal> if query is cacheble otherwise
<literal>FALSE</literal>.
</entry>
</row>
<row>
<entry>
<literal>no_table</literal>
</entry>
<entry>
<literal>TRUE</literal> if the query has generated a result
set and at least one column from the result set has no table
name set in its metadata. This is usually the case with
queries which one probably do not want to cache such as
<literal>SELECT SLEEP(1)</literal>. By default any such query
will not be added to the cache. See also PHP configuration directive
<literal>mysqlnd_qc.cache_no_table</literal>.
</entry>
</row>
<row>
<entry>
<literal>was_added</literal>
</entry>
<entry>
<literal>TRUE</literal> if the query result has been put into
the cache, otherwise
<literal>FALSE</literal>.
</entry>
</row>
<row>
<entry>
<literal>was_already_in_cache</literal>
</entry>
<entry>
<literal>TRUE</literal> if the query result would have been
added to the cache if it was not already in the cache (cache hit).
Otherwise
<literal>FALSE</literal>.
</entry>
</row>
</entry>
</row>
<row>
<entry>
<literal>origin</literal>
</entry>
<entry>
Code backtrace.
</entry>
</row>
<row>
<entry>
<literal>run_time</literal>
</entry>
<entry>
Query run time in milliseconds. The collection of
of all times and the necessary
<literal>gettimeofday</literal>
system calls can be disabled by setting the PHP configuration
directive
<literal>mysqlnd_qc.time_statistics</literal> to
<literal>0</literal>
</entry>
</row>
<row>
<entry>
<literal>store_time</literal>
</entry>
<entry>
Query result set store time in milliseconds. The collection of
of all times and the necessary
<literal>gettimeofday</literal>
system calls can be disabled by setting the PHP configuration
directive
<literal>mysqlnd_qc.time_statistics</literal> to
<literal>0</literal>
</entry>
</row>
<row>
<entry>
<literal>eligible_for_caching</literal>
</entry>
<entry>
<literal>TRUE</literal> if query is cacheble otherwise
<literal>FALSE</literal>.
</entry>
</row>
<row>
<entry>
<literal>no_table</literal>
</entry>
<entry>
<literal>TRUE</literal> if the query has generated a result
set and at least one column from the result set has no table
name set in its metadata. This is usually the case with
queries which one probably do not want to cache such as
<literal>SELECT SLEEP(1)</literal>. By default any such query
will not be added to the cache. See also PHP configuration directive
<literal>mysqlnd_qc.cache_no_table</literal>.
</entry>
</row>
<row>
<entry>
<literal>was_added</literal>
</entry>
<entry>
<literal>TRUE</literal> if the query result has been put into
the cache, otherwise
<literal>FALSE</literal>.
</entry>
</row>
<row>
<entry>
<literal>was_already_in_cache</literal>
</entry>
<entry>
<literal>TRUE</literal> if the query result would have been
added to the cache if it was not already in the cache (cache hit).
Otherwise
<literal>FALSE</literal>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 role="examples">
<refsect1 role="examples">
&reftitle.examples;
<example>
<programlisting role="php">
<example>
<programlisting role="php">
<![CDATA[
<?php
/* Connect, create and populate test table */
@ -172,9 +172,9 @@ var_dump($res->fetch_assoc());
$res->free();
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
array(1) {
["id"]=>
@ -311,33 +311,33 @@ array(6) {
}
}
]]>
</screen>
</screen>
</example>
</refsect1>
</example>
</refsect1>
<refsect1 role="seealso">
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member>
<link linkend="mysqlnd-qc.configuration">Runtime configuration</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.collect-query-trace">mysqlnd_qc.collect_query_trace</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.query-trace-bt-depth">mysqlnd_qc.query_trace_bt_depth</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.time-statistics">mysqlnd_qc.time_statistics</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.cache-no-table">mysqlnd_qc.cache_no_table</link>
</member>
</simplelist>
</para>
</refsect1>
<para>
<simplelist>
<member>
<link linkend="mysqlnd-qc.configuration">Runtime configuration</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.collect-query-trace">mysqlnd_qc.collect_query_trace</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.query-trace-bt-depth">mysqlnd_qc.query_trace_bt_depth</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.time-statistics">mysqlnd_qc.time_statistics</link>
</member>
<member>
<link linkend="ini.mysqlnd-qc.cache-no-table">mysqlnd_qc.cache_no_table</link>
</member>
</simplelist>
</para>
</refsect1>
</refentry>

290
reference/mysqlnd_qc/functions/mysqlnd-qc-set-user-handlers.xml
View file

@ -2,168 +2,168 @@
<!-- $Revision$ -->
<refentry xml:id="function.mysqlnd_qc_set_user_handlers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_qc_set_user_handlers</refname>
<refpurpose>Sets the callback functions for a user-defined procedural storage handler</refpurpose>
</refnamediv>
<refnamediv>
<refname>mysqlnd_qc_set_user_handlers</refname>
<refpurpose>Sets the callback functions for a user-defined procedural storage handler</refpurpose>
</refnamediv>
<refsect1 role="description">
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type>
<methodname>mysqlnd_qc_set_user_handlers</methodname>
<methodparam>
<type>string</type>
<parameter>get_hash</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>find_query_in_cache</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>return_to_cache</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>add_query_to_cache_if_not_exists</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>query_is_select</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>update_query_run_time_stats</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>get_stats</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>clear_cache</parameter>
</methodparam>
</methodsynopsis>
<para>
Sets the callback functions for a user-defined procedural storage handler.
</para>
<methodsynopsis>
<type>bool</type>
<methodname>mysqlnd_qc_set_user_handlers</methodname>
<methodparam>
<type>string</type>
<parameter>get_hash</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>find_query_in_cache</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>return_to_cache</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>add_query_to_cache_if_not_exists</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>query_is_select</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>update_query_run_time_stats</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>get_stats</parameter>
</methodparam>
<methodparam>
<type>string</type>
<parameter>clear_cache</parameter>
</methodparam>
</methodsynopsis>
<para>
Sets the callback functions for a user-defined procedural storage handler.
</para>
</refsect1>
<refsect1 role="parameters">
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term>
<parameter>get_hash</parameter>
</term>
<listitem>
<para>
<variablelist>
<varlistentry>
<term>
<parameter>get_hash</parameter>
</term>
<listitem>
<para>
Name of the user function implementing the storage handler
<literal>get_hash</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>find_query_in_cache</parameter>
</term>
<listitem>
<para>
<literal>get_hash</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>find_query_in_cache</parameter>
</term>
<listitem>
<para>
Name of the user function implementing the storage handler
<literal>find_in_cache</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>return_to_cache</parameter>
</term>
<listitem>
<para>
<literal>find_in_cache</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>return_to_cache</parameter>
</term>
<listitem>
<para>
Name of the user function implementing the storage handler
<literal>return_to_cache</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>add_query_to_cache_if_not_exists</parameter>
</term>
<listitem>
<para>
<literal>return_to_cache</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>add_query_to_cache_if_not_exists</parameter>
</term>
<listitem>
<para>
Name of the user function implementing the storage handler
<literal>add_query_to_cache_if_not_exists</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>query_is_select</parameter>
</term>
<listitem>
<para>
<literal>add_query_to_cache_if_not_exists</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>query_is_select</parameter>
</term>
<listitem>
<para>
Name of the user function implementing the storage handler
<literal>query_is_select</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>update_query_run_time_stats</parameter>
</term>
<listitem>
<para>
<literal>query_is_select</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>update_query_run_time_stats</parameter>
</term>
<listitem>
<para>
Name of the user function implementing the storage handler
<literal>update_query_run_time_stats</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>get_stats</parameter>
</term>
<listitem>
<para>
<literal>update_query_run_time_stats</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>get_stats</parameter>
</term>
<listitem>
<para>
Name of the user function implementing the storage handler
<literal>get_stats</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>clear_cache</parameter>
</term>
<listitem>
<para>
<literal>get_stats</literal> functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>clear_cache</parameter>
</term>
<listitem>
<para>
Name of the user function implementing the storage handler
<literal>clear_cache</literal> functionality.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<literal>clear_cache</literal> functionality.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns TRUE on success or FALSE on FAILURE.
</para>
</refsect1>
<refsect1 role="seealso">
<para>
Returns TRUE on success or FALSE on FAILURE.
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member>
<link linkend="mysqlnd-qc.set_user_handlers">Procedural user-defined storage handler example</link>
</member>
</simplelist>
</para>
</refsect1>
<para>
<simplelist>
<member>
<link linkend="mysqlnd-qc.set_user_handlers">Procedural user-defined storage handler example</link>
</member>
</simplelist>
</para>
</refsect1>
</refentry>

742
reference/mysqlnd_qc/ini.xml
View file

@ -4,382 +4,382 @@
<section xml:id="mysqlnd-qc.configuration" xmlns="http://docbook.org/ns/docbook">
&reftitle.runtime;
&extension.runtime;
<para>
<table>
<title>mysqlnd_qc &ConfigureOptions;</title>
<tgroup cols="4">
<thead>
<row>
<entry>&Name;</entry>
<entry>&Default;</entry>
<entry>&Changeable;</entry>
<entry>&Changelog;</entry>
</row>
</thead>
<tbody>
<row>
<entry>mysqlnd_qc.enable_qc</entry>
<entry>1</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.ttl</entry>
<entry>30</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.cache_by_default</entry>
<entry>0</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.cache_no_table</entry>
<entry>0</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.use_request_time</entry>
<entry>0</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.time_statistics</entry>
<entry>1</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.collect_statistics</entry>
<entry>0</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.collect_query_trace</entry>
<entry>0</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.query_trace_bt_depth</entry>
<entry>3</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.slam_defense</entry>
<entry>0</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.slam_defense_ttl</entry>
<entry>30</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.collect_normalized_query_trace</entry>
<entry>0</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.std_data_copy</entry>
<entry>0</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.apc_prefix</entry>
<entry>qc_</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.memc_server</entry>
<entry>127.0.0.1</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.memc_port</entry>
<entry>11211</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.sqlite_data_file</entry>
<entry>:memory:</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<table>
<title>mysqlnd_qc &ConfigureOptions;</title>
<tgroup cols="4">
<thead>
<row>
<entry>&Name;</entry>
<entry>&Default;</entry>
<entry>&Changeable;</entry>
<entry>&Changelog;</entry>
</row>
</thead>
<tbody>
<row>
<entry>mysqlnd_qc.enable_qc</entry>
<entry>1</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.ttl</entry>
<entry>30</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.cache_by_default</entry>
<entry>0</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.cache_no_table</entry>
<entry>0</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.use_request_time</entry>
<entry>0</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.time_statistics</entry>
<entry>1</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.collect_statistics</entry>
<entry>0</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.collect_query_trace</entry>
<entry>0</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.query_trace_bt_depth</entry>
<entry>3</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.slam_defense</entry>
<entry>0</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.slam_defense_ttl</entry>
<entry>30</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.collect_normalized_query_trace</entry>
<entry>0</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.std_data_copy</entry>
<entry>0</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.apc_prefix</entry>
<entry>qc_</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.memc_server</entry>
<entry>127.0.0.1</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.memc_port</entry>
<entry>11211</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
<row>
<entry>mysqlnd_qc.sqlite_data_file</entry>
<entry>:memory:</entry>
<entry>PHP_INI_ALL</entry>
<entry><!-- leave empty, this will be filled by an automatic script -->
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
&ini.descriptions.title;
<para>
<variablelist>
<varlistentry xml:id="ini.mysqlnd-qc.enable-qc">
<term>
<parameter>mysqlnd_qc.enable_qc</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Enables or disables the plugin. If disabled the extension will not plug
into
<link linkend="book.mysqlnd">mysqlnd</link> to proxy internal
<link linkend="book.mysqlnd">mysqlnd</link> C API calls.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.ttl">
<term>
<parameter>mysqlnd_qc.ttl</parameter>
<type>integer</type>
</term>
<listitem>
<para>
<para>
<variablelist>
<varlistentry xml:id="ini.mysqlnd-qc.enable-qc">
<term>
<parameter>mysqlnd_qc.enable_qc</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Enables or disables the plugin. If disabled the extension will not plug
into
<link linkend="book.mysqlnd">mysqlnd</link> to proxy internal
<link linkend="book.mysqlnd">mysqlnd</link> C API calls.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.ttl">
<term>
<parameter>mysqlnd_qc.ttl</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Default Time-to-Live (TTL) for cache entries in seconds.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.cache-by-default">
<term>
<parameter>mysqlnd_qc.cache_by_default</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Cache all queries regardless if they begin with the SQL hint that
enables caching of a query or not. Storage handler cannot overrule
the setting. It is evaluated by the core of the plugin.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.cache-no-table">
<term>
<parameter>mysqlnd_qc.cache_no_table</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Cache queries with no table name in any of columns meta data
of their result set, e.g.
<literal>SELECT SLEEP(1)</literal>?
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.use-request-time">
<term>
<parameter>mysqlnd_qc.use_request_time</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Use PHP global request time to avoid
<literal>gettimeofday()</literal> system calls?
If using
<literal>
<link linkend="ref.apc">APC</link>
</literal> storage handler
it should be set to the value of
<literal>
<link linkend="apc.configuration">apc.use_request_time</link>
</literal>, if not
warnings will be generated.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.time-statistics">
<term>
<parameter>mysqlnd_qc.time_statistics</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Collect run time and store time statistics using
<literal>gettimeofday()</literal> system call? Data will be
collected only if you also set
<literal>mysqlnd_qc.collect_statistics = 1</literal>,
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.collect-statistics">
<term>
<parameter>mysqlnd_qc.collect_statistics</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Collect statistics for
<function>mysqlnd_qc_get_core_stats()</function>?
Does not influence storage handler statistics! Handler statistics
can be an integral part of the handler internal storage format.
Thereofore, collection of some handler statistics cannot be disabled.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.collect-query-trace">
<term>
<parameter>mysqlnd_qc.collect_query_trace</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Collect query back traces?
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.query-trace-bt-depth">
<term>
<parameter>mysqlnd_qc.query_trace_bt_depth</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Maximum depth/level of a query code backtrace.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.slam-defense">
<term>
<parameter>mysqlnd_qc.slam_defense</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Activates handler based slam defense if available.
Supported by
<literal>Default</literal> and
<literal>
<link linkend="ref.apc">APC</link>
</literal> storage handler
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.slam-defense-ttl">
<term>
<parameter>mysqlnd_qc.slam_defense_ttl</parameter>
<type>integer</type>
</term>
<listitem>
<para>
<literal>TTL</literal> for stale cache entries which are
served while another client updates the entries. Supported by
<literal>
<link linkend="ref.apc">APC</link>
</literal>
storage handler.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.collect-normalized-query-trace">
<term>
<parameter>mysqlnd_qc.collect_normalized_query_trace</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Collect aggregated normalized query traces? The setting
has no effect by default. You compile the extension
using the define
<literal>NORM_QUERY_TRACE_LOG</literal> to make use of the setting.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.std-data-copy">
<term>
<parameter>mysqlnd_qc.std_data_copy</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Default storage handler: copy cached wire data?
EXPERIMENTAL – use default setting!
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.apc-prefix">
<term>
<parameter>mysqlnd_qc.apc_prefix</parameter>
<type>string</type>
</term>
<listitem>
<para>
The
<literal>
<link linkend="ref.apc">APC</link>
</literal> storage handler stores data in the
<literal>APC</literal> user cache. The setting sets a prefix to be
used for cache entries.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.memc-server">
<term>
<parameter>mysqlnd_qc.memc_server</parameter>
<type>string</type>
</term>
<listitem>
<para>
<literal>MEMCACHE</literal> storage handler: memcache server host.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.memc-port">
<term>
<parameter>mysqlnd_qc.memc_port</parameter>
<type>integer</type>
</term>
<listitem>
<para>
<literal>MEMCACHE</literal> storage handler: memcached server port.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.sqlite-data-file">
<term>
<parameter>mysqlnd_qc.sqlite_data_file</parameter>
<type>string</type>
</term>
<listitem>
<para>
<literal>sqlite</literal> storage handler: data file. Any setting
but
<literal>:memory:</literal> may be of little practical value.
</para>
</listitem>
</varlistentry>
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.cache-by-default">
<term>
<parameter>mysqlnd_qc.cache_by_default</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Cache all queries regardless if they begin with the SQL hint that
enables caching of a query or not. Storage handler cannot overrule
the setting. It is evaluated by the core of the plugin.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.cache-no-table">
<term>
<parameter>mysqlnd_qc.cache_no_table</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Cache queries with no table name in any of columns meta data
of their result set, e.g.
<literal>SELECT SLEEP(1)</literal>?
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.use-request-time">
<term>
<parameter>mysqlnd_qc.use_request_time</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Use PHP global request time to avoid
<literal>gettimeofday()</literal> system calls?
If using
<literal>
<link linkend="ref.apc">APC</link>
</literal> storage handler
it should be set to the value of
<literal>
<link linkend="apc.configuration">apc.use_request_time</link>
</literal>, if not
warnings will be generated.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.time-statistics">
<term>
<parameter>mysqlnd_qc.time_statistics</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Collect run time and store time statistics using
<literal>gettimeofday()</literal> system call? Data will be
collected only if you also set
<literal>mysqlnd_qc.collect_statistics = 1</literal>,
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.collect-statistics">
<term>
<parameter>mysqlnd_qc.collect_statistics</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Collect statistics for
<function>mysqlnd_qc_get_core_stats()</function>?
Does not influence storage handler statistics! Handler statistics
can be an integral part of the handler internal storage format.
Thereofore, collection of some handler statistics cannot be disabled.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.collect-query-trace">
<term>
<parameter>mysqlnd_qc.collect_query_trace</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Collect query back traces?
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.query-trace-bt-depth">
<term>
<parameter>mysqlnd_qc.query_trace_bt_depth</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Maximum depth/level of a query code backtrace.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.slam-defense">
<term>
<parameter>mysqlnd_qc.slam_defense</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Activates handler based slam defense if available.
Supported by
<literal>Default</literal> and
<literal>
<link linkend="ref.apc">APC</link>
</literal> storage handler
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.slam-defense-ttl">
<term>
<parameter>mysqlnd_qc.slam_defense_ttl</parameter>
<type>integer</type>
</term>
<listitem>
<para>
<literal>TTL</literal> for stale cache entries which are
served while another client updates the entries. Supported by
<literal>
<link linkend="ref.apc">APC</link>
</literal>
storage handler.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.collect-normalized-query-trace">
<term>
<parameter>mysqlnd_qc.collect_normalized_query_trace</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Collect aggregated normalized query traces? The setting
has no effect by default. You compile the extension
using the define
<literal>NORM_QUERY_TRACE_LOG</literal> to make use of the setting.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.std-data-copy">
<term>
<parameter>mysqlnd_qc.std_data_copy</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Default storage handler: copy cached wire data?
EXPERIMENTAL – use default setting!
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.apc-prefix">
<term>
<parameter>mysqlnd_qc.apc_prefix</parameter>
<type>string</type>
</term>
<listitem>
<para>
The
<literal>
<link linkend="ref.apc">APC</link>
</literal> storage handler stores data in the
<literal>APC</literal> user cache. The setting sets a prefix to be
used for cache entries.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.memc-server">
<term>
<parameter>mysqlnd_qc.memc_server</parameter>
<type>string</type>
</term>
<listitem>
<para>
<literal>MEMCACHE</literal> storage handler: memcache server host.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.memc-port">
<term>
<parameter>mysqlnd_qc.memc_port</parameter>
<type>integer</type>
</term>
<listitem>
<para>
<literal>MEMCACHE</literal> storage handler: memcached server port.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-qc.sqlite-data-file">
<term>
<parameter>mysqlnd_qc.sqlite_data_file</parameter>
<type>string</type>
</term>
<listitem>
<para>
<literal>sqlite</literal> storage handler: data file. Any setting
but
<literal>:memory:</literal> may be of little practical value.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</variablelist>
</para>
</section>
<!-- Keep this comment at the end of the file

17
reference/mysqlnd_qc/setup.xml
View file

@ -7,18 +7,25 @@
<section xml:id="mysqlnd-qc.requirements">
&reftitle.required;
<para>
<literal>PHP 5.3.3</literal> or newer.
<literal>PHP 5.3.3</literal> or newer.
</para>
<para>
For using <literal><link linkend="ref.apc">APC</link></literal> storage handler: <literal>APC 3.1.3p1-beta</literal> or newer.
For using
<literal>
<link linkend="ref.apc">APC</link>
</literal> storage handler:
<literal>APC 3.1.3p1-beta</literal> or newer.
</para>
<para>
For using <literal>MEMCACHE</literal> storage handler: <literal>libmemcache 0.38</literal> or newer.
For using
<literal>MEMCACHE</literal> storage handler:
<literal>libmemcache 0.38</literal> or newer.
</para>
<para>
For using <literal>sqlite</literal> storage handler: <literal>sqlite3</literal> bundled with PHP.
For using
<literal>sqlite</literal> storage handler:
<literal>sqlite3</literal> bundled with PHP.
</para>
</section>
&reference.mysqlnd-qc.configure;

417
reference/mysqlnd_qc/usage.xml
View file

@ -4,93 +4,93 @@
<chapter xml:id="mysqlnd-qc.usage" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.examples;
<section xml:id="mysqlnd-qc.basic_usage" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Basic usage</title>
<para>
<section xml:id="mysqlnd-qc.basic_usage" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Basic usage</title>
<para>
The Query Cache plugin supports caching of queries issued by the following user API calls:
</para>
</para>
<para>
<para>
<itemizedlist>
<listitem>
<para>
<link linkend="ref.mysqli">mysqli</link>
<itemizedlist>
<listitem>
<para>
<link linkend="ref.mysqli">mysqli</link>
<itemizedlist>
<listitem>
<para>
<function>mysqli_query</function>
</para>
</listitem>
<listitem>
<para>
<function>mysqli_real_query</function> +
<function>mysqli_store_result</function>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>
<itemizedlist>
<listitem>
<para>
<function>PDO::query</function> if
<literal>PDO::ATTR_EMULATE_PREPARES = 1</literal> (default setting)
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<link linkend="ref.mysql">mysql</link>
<itemizedlist>
<listitem>
<para>
<function>mysql_query</function>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<function>mysqli_query</function>
</para>
</listitem>
<listitem>
<para>
<function>mysqli_real_query</function> +
<function>mysqli_store_result</function>
</para>
</listitem>
</itemizedlist>
</para>
<para>
A query which shall be cached must begin with the SQL hint
<literal>/*qc=on*/</literal>. It is recommended to use the PHP constant
<literal>
<link linkend="mysqlnd-qc.constants">MYSQLND_QC_ENABLE_SWITCH</link>
</literal> instead of using the string value.
</para>
<para>
</para>
</listitem>
<listitem>
<para>
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>
<itemizedlist>
<listitem>
<para>
uncached:
<literal>SELECT id FROM test</literal>
</para>
</listitem>
<listitem>
<para>
cached:
<literal>/*qc=on*/SELECT id FROM test</literal>
</para>
</listitem>
<listitem>
<para>
<function>PDO::query</function> if
<literal>PDO::ATTR_EMULATE_PREPARES = 1</literal> (default setting)
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example using the most advanced PHP MySQL API, which is
<literal>
<link linkend="ref.mysqli">mysqli</link>
</literal>:
</para>
<para>
<example>
<programlisting role="php">
</para>
</listitem>
<listitem>
<para>
<link linkend="ref.mysql">mysql</link>
<itemizedlist>
<listitem>
<para>
<function>mysql_query</function>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
<para>
A query which shall be cached must begin with the SQL hint
<literal>/*qc=on*/</literal>. It is recommended to use the PHP constant
<literal>
<link linkend="mysqlnd-qc.constants">MYSQLND_QC_ENABLE_SWITCH</link>
</literal> instead of using the string value.
</para>
<para>
<itemizedlist>
<listitem>
<para>
uncached:
<literal>SELECT id FROM test</literal>
</para>
</listitem>
<listitem>
<para>
cached:
<literal>/*qc=on*/SELECT id FROM test</literal>
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example using the most advanced PHP MySQL API, which is
<literal>
<link linkend="ref.mysqli">mysqli</link>
</literal>:
</para>
<para>
<example>
<programlisting role="php">
<![CDATA[
<?php
/* Enable collection of query cache statistics */
@ -120,9 +120,9 @@ printf("Cache put\t: %d\n", $stats['cache_put']);
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
array(1) {
["id"]=>
@ -136,45 +136,45 @@ Cache hit : 0
Cache miss : 1
Cache put : 1
]]>
</screen>
</screen>
</example>
</para>
<para>
The default invalidation strategy of the cache is Time-to-Live (
<literal>TTL</literal>). Cache entries are valid for a certain duration.
The default duration is set by the PHP configuration directive
<literal>
<link linkend="mysqlnd-qc.configuration">mysqlnd_qc.tll</link>
</literal>
</para>
</section>
</example>
</para>
<para>
The default invalidation strategy of the cache is Time-to-Live (
<literal>TTL</literal>). Cache entries are valid for a certain duration.
The default duration is set by the PHP configuration directive
<literal>
<link linkend="mysqlnd-qc.configuration">mysqlnd_qc.tll</link>
</literal>
</para>
</section>
<section xml:id="mysqlnd-qc.per_query_ttl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Setting the TTL</title>
<para>
The default invalidation strategy of the query cache plugin is Time-to-Live (
<literal>TTL</literal>). The built-in storage handler will use the default
<literal>TTL</literal> defined by the PHP configuration value
<literal>
<link linkend="mysqlnd-qc.configuration">mysqlnd_qc.ttl</link>
</literal> unless the query string contains
a hint for setting a different
<literal>TTL</literal>. The
<literal>TTL</literal> is specified in seconds.
</para>
<para>
Any
<literal>TTL</literal> based cache can serve stale data. Cache entries
are not automatically invalidated, if underlying data changes.
</para>
<para>
User-defined cache storage handler can implement any invalidation strategy
to work around this limitation.
</para>
<para>
<example>
<programlisting role="php">
<section xml:id="mysqlnd-qc.per_query_ttl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Setting the TTL</title>
<para>
The default invalidation strategy of the query cache plugin is Time-to-Live (
<literal>TTL</literal>). The built-in storage handler will use the default
<literal>TTL</literal> defined by the PHP configuration value
<literal>
<link linkend="mysqlnd-qc.configuration">mysqlnd_qc.ttl</link>
</literal> unless the query string contains
a hint for setting a different
<literal>TTL</literal>. The
<literal>TTL</literal> is specified in seconds.
</para>
<para>
Any
<literal>TTL</literal> based cache can serve stale data. Cache entries
are not automatically invalidated, if underlying data changes.
</para>
<para>
User-defined cache storage handler can implement any invalidation strategy
to work around this limitation.
</para>
<para>
<example>
<programlisting role="php">
<![CDATA[
<?php
/* Connect, create and populate test table */
@ -206,9 +206,9 @@ $res->free();
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
Default TTL: : 30 seconds
array(1) {
@ -221,24 +221,23 @@ array(1) {
}
NULL
]]>
</screen>
</screen>
</example>
</para>
<para>
The default
<literal>TTL</literal> can be overruled using the SQL hint
<literal>/*qc_tt=seconds*/</literal>. The SQL hint must be appear immediately
after the SQL hint which enables caching. It is recommended to use
the PHP constant
<literal>
<link linkend="mysqlnd-qc.constants">MYSQLND_QC_TTL_SWITCH</link>
</literal> instead of
using the string value.
</para>
<para>
<example>
<programlisting role="php">
</example>
</para>
<para>
The default
<literal>TTL</literal> can be overruled using the SQL hint
<literal>/*qc_tt=seconds*/</literal>. The SQL hint must be appear immediately
after the SQL hint which enables caching. It is recommended to use
the PHP constant
<literal>
<link linkend="mysqlnd-qc.constants">MYSQLND_QC_TTL_SWITCH</link>
</literal> instead of using the string value.
</para>
<para>
<example>
<programlisting role="php">
<![CDATA[
<?php
$start = microtime(true);
@ -279,9 +278,9 @@ printf("Script runtime\t: %d seconds\n", microtime(true) - $start);
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
Default TTL : 30 seconds
array(1) {
@ -296,46 +295,44 @@ NULL
Script runtime : 3 seconds
]]>
</screen>
</screen>
</example>
</para>
</example>
</para>
</section>
</section>
<section xml:id="mysqlnd-qc.cache_by_default" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Cache by default</title>
<para>
The query cache plugin will cache all queries regardless if
the query string begins with the SQL hint which enables caching or not,
if the PHP configuration directive
<literal>
<link linkend="mysqlnd-qc.configuration">mysqlnd_qc.cache_by_default</link>
</literal> is set to
<literal>1</literal>.
The setting
<literal>
<link linkend="mysqlnd-qc.configuration">mysqlnd_qc.cache_by_default</link>
</literal> is evaluated
by the core of the query cache plugins. Neither the built-in nor
user-defined storage handler can overrule the setting.
</para>
<para>
The SQL hint
<literal>/*qc=off*/</literal> can be used to disable caching
of individual queries if
<literal>
<link linkend="mysqlnd-qc.configuration">mysqlnd_qc.cache_by_default = 1</link>
</literal>
It is recommended to use the PHP constant
<literal>
<link linkend="mysqlnd-qc.constants">MYSQLND_QC_DISABLE_SWITCH</link>
</literal> instead of
using the string value.
</para>
<para>
<example>
<programlisting role="php">
<section xml:id="mysqlnd-qc.cache_by_default" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Cache by default</title>
<para>
The query cache plugin will cache all queries regardless if
the query string begins with the SQL hint which enables caching or not,
if the PHP configuration directive
<literal>
<link linkend="mysqlnd-qc.configuration">mysqlnd_qc.cache_by_default</link>
</literal> is set to
<literal>1</literal>.
The setting
<literal>
<link linkend="mysqlnd-qc.configuration">mysqlnd_qc.cache_by_default</link>
</literal> is evaluated by the core of the query cache plugins.
Neither the built-in nor user-defined storage handler can overrule the setting.
</para>
<para>
The SQL hint
<literal>/*qc=off*/</literal> can be used to disable caching
of individual queries if
<literal>
<link linkend="mysqlnd-qc.configuration">mysqlnd_qc.cache_by_default = 1</link>
</literal>
It is recommended to use the PHP constant
<literal>
<link linkend="mysqlnd-qc.constants">MYSQLND_QC_DISABLE_SWITCH</link>
</literal> instead of using the string value.
</para>
<para>
<example>
<programlisting role="php">
<![CDATA[
<?php
/* Enable default caching of all statements */
@ -367,9 +364,9 @@ $res->free();
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
array(1) {
["id"]=>
@ -381,33 +378,33 @@ array(1) {
}
NULL
]]>
</screen>
</screen>
</example>
</para>
</section>
</example>
</para>
</section>
<section xml:id="mysqlnd-qc.set_user_handlers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Procedural user-defined storage handler</title>
<para>
The query cache plugin supports the use of user-defined storage handler.
User-defined storage handler can use arbitrarily complex invalidation
algorithms and support arbitrary storage media.
</para>
<para>
All user-defined storage handlers have to provide a certain interface.
The functions of the user-defined storage handler will be called by the
core of the cache plugin. The necessary interface consists of seven
public functions. Both procedural and object oriented user-defined storage
handler must implement the same set of functions.
</para>
<para>
Please check the example for details.
</para>
<para>
<example>
<programlisting role="php">
<section xml:id="mysqlnd-qc.set_user_handlers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Procedural user-defined storage handler</title>
<para>
The query cache plugin supports the use of user-defined storage handler.
User-defined storage handler can use arbitrarily complex invalidation
algorithms and support arbitrary storage media.
</para>
<para>
All user-defined storage handlers have to provide a certain interface.
The functions of the user-defined storage handler will be called by the
core of the cache plugin. The necessary interface consists of seven
public functions. Both procedural and object oriented user-defined storage
handler must implement the same set of functions.
</para>
<para>
Please check the example for details.
</para>
<para>
<example>
<programlisting role="php">
<![CDATA[
<?php
/* Enable default caching of all statements */
@ -565,9 +562,9 @@ var_dump($res->fetch_assoc());
$res->free();
?>
]]>
</programlisting>
</programlisting>
&examples.outputs;
<screen>
<screen>
<![CDATA[
query_is_select('DROP TABLE IF EXISTS test'): FALSE
query_is_select('CREATE TABLE test(id INT)'): FALSE
@ -629,11 +626,11 @@ bool(true)
NULL
]]>
</screen>
</screen>
</example>
</para>
</section>
</example>
</para>
</section>
</chapter>