mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 18:38:55 +00:00
04b11e621f
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@329325 c90b9560-bf6c-de11-be94-00142212c4b1
551 lines
16 KiB
XML
551 lines
16 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $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>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>array</type>
|
|
<methodname>mysqlnd_qc_get_cache_info</methodname>
|
|
<void />
|
|
</methodsynopsis>
|
|
<para>
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
&no.function.parameters;
|
|
</refsect1>
|
|
|
|
<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>
|
|
<para>
|
|
The scope of the information is the PHP process. Depending on the PHP deployment
|
|
model a process may serve one or more web requests.
|
|
</para>
|
|
<para>
|
|
Values are aggregated for all cache activities on a per storage handler basis.
|
|
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. Use
|
|
<function>mysqlnd_qc_get_core_stats</function>
|
|
to get timing data aggregated for all storage handlers.
|
|
</para>
|
|
<para>
|
|
Array of cache information
|
|
</para>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>handler</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
The active storage handler.
|
|
</para>
|
|
<para>
|
|
All storage handler. Since 1.0.0.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>handler_version</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
The version of the active storage handler.
|
|
</para>
|
|
<para>
|
|
All storage handler. Since 1.0.0.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>num_entries</parameter>
|
|
<type>int</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
The number of cache entries. The value depends on the storage handler in use.
|
|
</para>
|
|
<para>
|
|
The default, APC and SQLite storage handler provide the actual
|
|
number of cache entries.
|
|
</para>
|
|
<para>
|
|
The MEMCACHE storage handler always returns <literal>0</literal>.
|
|
MEMCACHE does not support counting the number of cache entries.
|
|
</para>
|
|
<para>
|
|
If a user defined handler is used, the number of
|
|
entries of the <literal>data</literal> property is reported.
|
|
</para>
|
|
<para>
|
|
Since 1.0.0.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>data</parameter>
|
|
<type>array</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
The version of the active storage handler.
|
|
</para>
|
|
<para>
|
|
Additional storage handler dependent data on the cache entries.
|
|
Storage handler are requested to provide similar and comparable
|
|
information. A user defined storage handler is free to return any data.
|
|
</para>
|
|
<para>
|
|
Since 1.0.0.
|
|
</para>
|
|
<para>
|
|
The following information is provided by the default storage handler
|
|
for the <literal>data</literal> property.
|
|
</para>
|
|
<para>
|
|
The <literal>data</literal>
|
|
property holds a hash. The hash is indexed by the internal
|
|
cache entry identifier of the storage handler. The cache entry identifier
|
|
is human-readable and contains the query string leading to the cache entry.
|
|
Please, see also the example below. The following data is given for
|
|
every cache entry.
|
|
</para>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>statistics</parameter>
|
|
<type>array</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Statistics of the cache entry.
|
|
</para>
|
|
<para>
|
|
Since 1.0.0.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="3">
|
|
<colspec colwidth="1*"/>
|
|
<colspec colwidth="7*"/>
|
|
<colspec colwidth="2*"/>
|
|
<thead>
|
|
<row>
|
|
<entry>Property</entry>
|
|
<entry>Description</entry>
|
|
<entry>Version</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<literal>rows</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of rows of the cached result set.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>stored_size</literal>
|
|
</entry>
|
|
<entry>
|
|
The size of the cached result set in bytes. This is the size
|
|
of the payload. The value is not suited for calculating the
|
|
total memory consumption of all cache entries including the
|
|
administrative overhead of the cache entries.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>cache_hits</literal>
|
|
</entry>
|
|
<entry>
|
|
How often the cached entry has been returned.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>run_time</literal>
|
|
</entry>
|
|
<entry>
|
|
Run time of the statement to which the cache entry belongs.
|
|
This is the run time of the uncached statement. It is the time
|
|
between sending the statement to MySQL receiving a reply from MySQL.
|
|
Run time saved by using the query cache plugin can be calculated
|
|
like this: <literal>cache_hits * ((run_time - avg_run_time) + (store_time - avg_store_time))</literal>.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>store_time</literal>
|
|
</entry>
|
|
<entry>
|
|
Store time of the statements result set to which the cache entry belongs.
|
|
This is the time it took to fetch and store the results of the uncached
|
|
statement.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>min_run_time</literal>
|
|
</entry>
|
|
<entry>
|
|
Minimum run time of the cached statement. How long it took
|
|
to find the statement in the cache.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>min_store_time</literal>
|
|
</entry>
|
|
<entry>
|
|
Minimum store time of the cached statement. The time taken
|
|
for fetching the cached result set from the storage medium and
|
|
decoding
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>avg_run_time</literal>
|
|
</entry>
|
|
<entry>
|
|
Average run time of the cached statement.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>avg_store_time</literal>
|
|
</entry>
|
|
<entry>
|
|
Average store time of the cached statement.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>max_run_time</literal>
|
|
</entry>
|
|
<entry>
|
|
Average run time of the cached statement.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>max_store_time</literal>
|
|
</entry>
|
|
<entry>
|
|
Average store time of the cached statement.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>valid_until</literal>
|
|
</entry>
|
|
<entry>
|
|
Timestamp when the cache entry expires.
|
|
</entry>
|
|
<entry>Since 1.1.0.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>metadata</parameter>
|
|
<type>array</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Metadata of the cache entry.
|
|
This is the metadata provided by MySQL together with the
|
|
result set of the statement in question. Different versions
|
|
of the MySQL server may return different metadata. Unlike with
|
|
some of the PHP MySQL extensions no attempt is made to hide
|
|
MySQL server version dependencies and version details from the
|
|
caller. Please, refer to the MySQL C API documentation that
|
|
belongs to the MySQL server in use for further details.
|
|
</para>
|
|
<para>
|
|
The metadata list contains one entry for every column.
|
|
</para>
|
|
<para>
|
|
Since 1.0.0.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="3">
|
|
<colspec colwidth="1*"/>
|
|
<colspec colwidth="7*"/>
|
|
<colspec colwidth="2*"/>
|
|
<thead>
|
|
<row>
|
|
<entry>Property</entry>
|
|
<entry>Description</entry>
|
|
<entry>Version</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<literal>name</literal>
|
|
</entry>
|
|
<entry>
|
|
The field name. Depending on the MySQL version this
|
|
may be the fields alias name.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>org_name</literal>
|
|
</entry>
|
|
<entry>
|
|
The field name.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>table</literal>
|
|
</entry>
|
|
<entry>
|
|
The table name. If an alias name was used for the table, this
|
|
usually holds the alias name.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>org_table</literal>
|
|
</entry>
|
|
<entry>
|
|
The table name.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>db</literal>
|
|
</entry>
|
|
<entry>
|
|
The database/schema name.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>max_length</literal>
|
|
</entry>
|
|
<entry>
|
|
The maximum width of the field. Details may vary by MySQL server version.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>length</literal>
|
|
</entry>
|
|
<entry>
|
|
The width of the field. Details may vary by MySQL server version.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>type</literal>
|
|
</entry>
|
|
<entry>
|
|
The data type of the field. Details may vary by the MySQL server in use.
|
|
This is the MySQL C API type constants value. It is recommended
|
|
to use type constants provided by the <literal>mysqli</literal> extension
|
|
to test for its meaning. You should not test for certain type values
|
|
by comparing with certain numbers.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
The APC storage handler returns the same information
|
|
for the <literal>data</literal> property but no <literal>metadata</literal>.
|
|
The <literal>metadata</literal> of a cache entry is set to <literal>NULL</literal>.
|
|
</para>
|
|
<para>
|
|
The MEMCACHE storage handler does not fill the <literal>data</literal> property.
|
|
Statistics are not available on a per cache entry basis with the MEMCACHE storage
|
|
handler.
|
|
</para>
|
|
<para>
|
|
A user defined storage handler is free to provide any data.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<example>
|
|
<title><function>mysqlnd_qc_get_cache_info</function> example</title>
|
|
<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 */
|
|
$mysqli = new mysqli("host", "user", "password", "schema");
|
|
$mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/SELECT id FROM test");
|
|
|
|
/* Display cache information */
|
|
var_dump(mysqlnd_qc_get_cache_info());
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&examples.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
array(4) {
|
|
["num_entries"]=>
|
|
int(1)
|
|
["handler"]=>
|
|
string(7) "default"
|
|
["handler_version"]=>
|
|
string(5) "1.0.0"
|
|
["data"]=>
|
|
array(1) {
|
|
["Localhost via UNIX socket 3306 user schema|/*qc=on*/SELECT id FROM test"]=>
|
|
array(2) {
|
|
["statistics"]=>
|
|
array(11) {
|
|
["rows"]=>
|
|
int(6)
|
|
["stored_size"]=>
|
|
int(101)
|
|
["cache_hits"]=>
|
|
int(0)
|
|
["run_time"]=>
|
|
int(471)
|
|
["store_time"]=>
|
|
int(27)
|
|
["min_run_time"]=>
|
|
int(0)
|
|
["max_run_time"]=>
|
|
int(0)
|
|
["min_store_time"]=>
|
|
int(0)
|
|
["max_store_time"]=>
|
|
int(0)
|
|
["avg_run_time"]=>
|
|
int(0)
|
|
["avg_store_time"]=>
|
|
int(0)
|
|
}
|
|
["metadata"]=>
|
|
array(1) {
|
|
[0]=>
|
|
array(8) {
|
|
["name"]=>
|
|
string(2) "id"
|
|
["orig_name"]=>
|
|
string(2) "id"
|
|
["table"]=>
|
|
string(4) "test"
|
|
["orig_table"]=>
|
|
string(4) "test"
|
|
["db"]=>
|
|
string(4) "schema"
|
|
["max_length"]=>
|
|
int(1)
|
|
["length"]=>
|
|
int(11)
|
|
["type"]=>
|
|
int(3)
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member>
|
|
<function>mysqlnd_qc_get_core_stats</function>
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|