[doc-en] master: ext/yac: Add a Memory Management chapter and improve the examples (#5822)
| From: | Xinchen Hui via GitHub | Date: | Wed, 02 Sep 2026 07:54:50 +0000 |
| Subject: | [doc-en] master: ext/yac: Add a Memory Management chapter and improve the examples (#5822) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23694@lists.php.net to get a copy of this message | ||
Author: Xinchen Hui (laruence)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-09-02T09:54:47+02:00
Commit: https://github.com/php/doc-en/commit/c05fbe7250c43b75034ac776ed78f4e67163e4d3
Raw diff: https://github.com/php/doc-en/commit/c05fbe7250c43b75034ac776ed78f4e67163e4d3.diff
ext/yac: Add a Memory Management chapter and improve the examples (#5822)
Add a Memory Management chapter that explains the two independent
shared-memory pools:
- the key pool: a fixed-size slot table; expired and deleted slots are
reused for free, and only a probe path of four live entries triggers
an eviction (the least recently used, then the least hit), counted
in the kicks counter
- the value pool: 4M segments with a wrap-around allocator whose
recycles overwrite the oldest values, detected by a CRC integrity
guard and turned into misses
Document how to size both pools and how to read the Yac::info counters
(interval hit rate, kicks, recycles, fails) so each number maps to a
concrete action.
Also improve the examples:
- split the combined add/set/get/delete examples into one runnable
example per parameter form (single key, TTL, array form, default
value, delayed deletion), each self-contained
- fix the Yac::dump paging example, which returned an empty array on
an empty cache while claiming int(100), and correct the per-entry
hits reset semantics (reset on overwrite, not on delete or expiry)
Further fixes:
- fill the empty constant descriptions (YAC_VERSION,
YAC_MAX_VALUE_RAW_LEN, YAC_MAX_RAW_COMPRESSED_LEN) and fix typos
- align the synopsis parameter names with the arginfo ($keys -> $key)
- document compress_threshold clamping (1024..1M, -1 disables) and the
1 MB stored-size / 64 MB raw-size limits
- drop the stale configure.xml template (duplicated the installation
section of setup.xml)
Changed paths:
A reference/yac/memory.xml
D reference/yac/configure.xml
M reference/yac/book.xml
M reference/yac/constants.xml
M reference/yac/ini.xml
M reference/yac/yac/add.xml
M reference/yac/yac/delete.xml
M reference/yac/yac/dump.xml
M reference/yac/yac/get.xml
M reference/yac/yac/info.xml
M reference/yac/yac/set.xml
Diff:
diff --git a/reference/yac/book.xml b/reference/yac/book.xml
index c0aba1418ee6..eb137f716dcf 100644
--- a/reference/yac/book.xml
+++ b/reference/yac/book.xml
@@ -25,7 +25,8 @@
path, a read is essentially a hash lookup in shared memory. As a
result, Yac is extremely fast, with microsecond-level read
latency, and its throughput can scale with the number of
- workers as long as writes are spread across keys.
+ workers as long as writes are spread across keys; see the
+ <link
xlink:href="&url.git.hub;laruence/yac/blob/master/README.md#benchmarks">benchmarks</link>.
</simpara>
<simpara>
Because Yac trades correctness guarantees for speed and throughput,
@@ -36,8 +37,9 @@
</simpara>
<simpara>
As of yac 2.4.0, small scalar values —
- <constant>NULL</constant>, booleans, integers, short strings of up to
- 7 bytes and empty arrays — are stored directly inside the hash slot
+ <constant>NULL</constant>, booleans, most integers (those that fit in
+ 60 signed bits on 64-bit builds), strings of up to 7 bytes and empty
+ arrays — are stored directly inside the hash slot
instead of in a separate value block ("embedded values"), which
removes the value-memory allocation and block copy on every access
and significantly improves performance while reducing memory usage.
@@ -54,6 +56,7 @@
</preface>
&reference.yac.setup;
+ &reference.yac.memory;
&reference.yac.constants;
<!-- &reference.yac.examples; -->
&reference.yac.yac;
diff --git a/reference/yac/configure.xml b/reference/yac/configure.xml
deleted file mode 100644
index d003246fda54..000000000000
--- a/reference/yac/configure.xml
+++ /dev/null
@@ -1,35 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-
-<section xml:id="yac.installation" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
- &reftitle.install;
-
- <para>
- &pecl.info;
- <link
xlink:href="&url.pecl.package;yac">&url.pecl.package;yac</link>
- </para>
-
-
-</section>
-
-
-<!-- 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
--->
diff --git a/reference/yac/constants.xml b/reference/yac/constants.xml
index a6c06d0eefbe..279d23bcde75 100644
--- a/reference/yac/constants.xml
+++ b/reference/yac/constants.xml
@@ -13,6 +13,7 @@
</term>
<listitem>
<simpara>
+ The version of the extension as a string.
</simpara>
</listitem>
</varlistentry>
@@ -23,7 +24,8 @@
</term>
<listitem>
<simpara>
- Max length of a key could be, it is 48 bytes.
+ Maximum length of a key in bytes: 48. An instance prefix counts
+ against this limit.
</simpara>
</listitem>
</varlistentry>
@@ -34,6 +36,9 @@
</term>
<listitem>
<simpara>
+ Maximum length of a value before serialization, in bytes:
+ 67,108,863 (<literal>(1 << 26) - 1</literal>). Larger values
+ are rejected.
</simpara>
</listitem>
</varlistentry>
@@ -44,6 +49,8 @@
</term>
<listitem>
<simpara>
+ Maximum size of a stored entry, in bytes: 1,048,576 (1M). Values
+ that do not fit even after compression are rejected.
</simpara>
</listitem>
</varlistentry>
@@ -54,7 +61,7 @@
</term>
<listitem>
<simpara>
- Use php serialize as serializer
+ Use the PHP serialize format as serializer (the default).
</simpara>
</listitem>
</varlistentry>
@@ -65,7 +72,8 @@
</term>
<listitem>
<simpara>
- Use json as serializer(requrie --enable-json)
+ Use JSON as the serializer. Requires the extension to be built with
+ <option role="configure">--enable-json</option>.
</simpara>
</listitem>
</varlistentry>
@@ -76,7 +84,8 @@
</term>
<listitem>
<simpara>
- Use igbinary as serializer(require --enable-igbinary)
+ Use igbinary as the serializer. Requires the extension to be built
+ with <option role="configure">--enable-igbinary</option>.
</simpara>
</listitem>
</varlistentry>
@@ -87,7 +96,8 @@
</term>
<listitem>
<simpara>
- Use msgpack as serializer(require --enable-msgpack)
+ Use msgpack as the serializer. Requires the extension to be built
+ with <option role="configure">--enable-msgpack</option>.
</simpara>
</listitem>
</varlistentry>
@@ -98,7 +108,7 @@
</term>
<listitem>
<simpara>
- Which serialzier is yac used
+ The serializer currently used by the extension.
</simpara>
</listitem>
</varlistentry>
diff --git a/reference/yac/ini.xml b/reference/yac/ini.xml
index c9bf9f9551ba..cbf54bbd01d1 100644
--- a/reference/yac/ini.xml
+++ b/reference/yac/ini.xml
@@ -19,7 +19,7 @@
<tbody>
<row>
<entry><link
linkend="ini.yac.compress-threshold">yac.compress_threshold</link></entry>
- <entry>-1</entry>
+ <entry>4K</entry>
<entry><constant>INI_SYSTEM</constant></entry>
<entry><!-- leave empty, this will be filled by an automatic script
--></entry>
</row>
@@ -43,7 +43,7 @@
</row>
<row>
<entry><link
linkend="ini.yac.keys-memory-size">yac.keys_memory_size</link></entry>
- <entry>4M</entry>
+ <entry>8M</entry>
<entry><constant>INI_SYSTEM</constant></entry>
<entry><!-- leave empty, this will be filled by an automatic script
--></entry>
</row>
@@ -76,10 +76,17 @@
<listitem>
<simpara>
Serialized values larger than this number of bytes are
- compressed before being stored (currently with LZ4). Set it to
- <literal>-1</literal> (the default) to disable compression
- entirely. Compressing large values saves shared memory at the cost
- of some CPU on both store and retrieve.
+ compressed (with LZ4, since Yac 2.4.0) before being stored.
+ Values above the <literal>1M</literal> stored entry limit
+ (<constant>YAC_MAX_RAW_COMPRESSED_LEN</constant>) are always
+ compressed regardless of this setting, because they cannot be
+ stored uncompressed. The default of <literal>4K</literal>
+ enables compression; <literal>-1</literal> disables it for
+ values below the stored entry limit, and other positive values
+ are clamped to the
+ <literal>1024</literal>..<literal>1M</literal> range.
+ Compressing large values saves shared memory at the cost of
+ some CPU on both store and retrieve.
</simpara>
</listitem>
</varlistentry>
@@ -128,12 +135,30 @@
</term>
<listitem>
<simpara>
- Amount of shared memory used for the hash slots that hold keys
- and bookkeeping. Each slot is a fixed-size structure, so this value
- determines how many items can be tracked at once. Defaults to
- <literal>4M</literal>. Yac splits this area into segments; the
- segment size is 4M, so this value must be a multiple of
- <literal>4M</literal>.
+ Amount of shared memory for the table of keys. It caps how many
+ entries can exist at once — the default of
+ <literal>8M</literal> gives around 65,536 entries. Raise this
+ when the hit rate drops and <literal>kicks</literal> climb; see
+ <xref linkend="yac.memory-management"/> for how a full table
+ behaves and when that actually matters.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="ini.yac.values-memory-size">
+ <term>
+ <parameter>yac.values_memory_size</parameter>
+ <type>string</type>
+ </term>
+ <listitem>
+ <simpara>
+ Amount of shared memory for storing values. Values are allocated
+ in a bump allocator over segments of 4M each; when no segment has
+ room for a new value, an allocator cursor wraps and the oldest
+ values are silently overwritten ("recycled"). Their reads then
+ degrade to misses, detected by an integrity guard. Enlarge this
+ if <literal>recycles</literal> climb while slots still have room,
+ or enable <link
linkend="ini.yac.compress-threshold">yac.compress_threshold</link>
+ to shrink large payloads. See <xref linkend="yac.memory-management"/>.
</simpara>
</listitem>
</varlistentry>
@@ -155,21 +180,6 @@
</simpara>
</listitem>
</varlistentry>
- <varlistentry xml:id="ini.yac.values-memory-size">
- <term>
- <parameter>yac.values_memory_size</parameter>
- <type>string</type>
- </term>
- <listitem>
- <simpara>
- Amount of shared memory used to store the actual values.
- Defaults to <literal>64M</literal>. Yac allocates this area in
- segments of 4M each, so this value must be a multiple of
- <literal>4M</literal>. When the area is full, least recently used
- entries are kicked to make room for new ones.
- </simpara>
- </listitem>
- </varlistentry>
</variablelist>
</para>
diff --git a/reference/yac/memory.xml b/reference/yac/memory.xml
new file mode 100644
index 000000000000..fce411d067f6
--- /dev/null
+++ b/reference/yac/memory.xml
@@ -0,0 +1,245 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<chapter xml:id="yac.memory-management" xmlns="http://docbook.org/ns/docbook">
+ <title>Memory Management</title>
+
+ <simpara>
+ Yac keeps its data in two independent shared-memory pools, configured
+ with
+ <link linkend="ini.yac.keys-memory-size">yac.keys_memory_size</link>
+ and
+ <link linkend="ini.yac.values-memory-size">yac.values_memory_size</link>.
+ They fill up and free up in different ways, so it helps to know which
+ pool a symptom belongs to before touching either knob.
+ </simpara>
+
+ <section xml:id="yac.memory-layout" annotations="chunk:false">
+ <title>What Each Pool Holds</title>
+ <simpara>
+ The two pools store different halves of an entry. The key pool holds
+ the keys: one slot per cached key, carrying the key itself (up to 48
+ bytes) together with its hash, TTL, hit count and last-access time;
+ the value is only referenced through a pointer to the value pool. The
+ value pool holds the values: every stored value occupies one block of
+ serialized bytes — the compressed form when the entry went through
+ <link linkend="ini.yac.compress-threshold">yac.compress_threshold</link>.
+ </simpara>
+ <simpara>
+ The one exception is embedded values: tiny scalars — &null;,
+ &true;, &false;, most integers (those that fit in 60 signed bits on
+ 64-bit builds), strings of up to 7 bytes and empty arrays — are
+ stored directly inside the slot, in the pointer that would otherwise
+ reference a block. Such values occupy no space in the value pool at
+ all; only their key does.
+ </simpara>
+ <para>
+ As a rough sizing guide:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ the key pool holds around 8,000 keys per MB, so size
+ <link linkend="ini.yac.keys-memory-size">yac.keys_memory_size</link>
+ as the number of distinct keys divided by 8,000 per MB, rounded up
+ — the default <literal>8M</literal> holds around 64,000 keys;
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ the value pool must hold every value that may still be read, so
+ size
+ <link
linkend="ini.yac.values-memory-size">yac.values_memory_size</link>
+ as the number of live values times their average serialized size
+ (after compression), and allow roughly twice that: the pool is a
+ ring, and a value only dies once the allocator cursor comes back
+ around to overwrite it.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ Embedded values occupy a slot like any other entry, but consume no
+ space in the value pool, so leave them out of the second calculation.
+ </para>
+ </section>
+
+ <section xml:id="yac.memory-keys" annotations="chunk:false">
+ <title>The key pool (slots)</title>
+ <simpara>
+ <link linkend="ini.yac.keys-memory-size">yac.keys_memory_size</link>
+ holds a fixed-size table of slots — the default of
+ <literal>8M</literal> gives around 65,536 slots. Each
+ stored key occupies exactly one slot, so this pool caps the number
+ of entries that can exist at once; unlike the value pool, slots are
+ never individually freed. An expired slot — one past its TTL, or the
+ tombstone left by <methodname>Yac::delete</methodname> — is recycled
+ for free when a new key needs it. Only when all four candidate slots
+ of a probe path hold live entries is one of them evicted to make
+ room — one <literal>kick</literal> (the
+ <literal>kicks</literal> counter of <methodname>Yac::info</methodname>).
+ </simpara>
+ <para>
+ The eviction picks among the four live candidates of the colliding
+ probe path only:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ the least recently used one (the oldest
+ <literal>atime</literal>) is evicted;
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ on a tie the least-hit entry, then the earliest probe position.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <simpara>
+ A common point of confusion: <literal>slots_used</literal> reaching
+ <literal>slots_size</literal> is <emphasis>not</emphasis> an error
+ condition. A cache whose working set of keys is larger than the slot
+ table simply runs at 100% occupancy from then on, evicting and
+ re-inserting as needed. The only thing that says whether the key
+ pool is sized correctly is the hit rate
+ (<literal>hits / (hits + miss)</literal>, computed over the deltas
+ between two <methodname>Yac::info</methodname> snapshots rather than
+ the lifetime average). A high <literal>kicks</literal> count on its
+ own means nothing is wrong — the key distribution is simply not
+ uniform and some probe paths collide more than others. Only when the
+ hit rate <emphasis>and</emphasis> <literal>kicks</literal> are both
+ bad is the table too small for the key set, and the remedy is a
+ bigger <link
linkend="ini.yac.keys-memory-size">yac.keys_memory_size</link>.
+ </simpara>
+ <simpara>
+ A second consequence of slots never being freed: entries with no TTL
+ (<literal>ttl = 0</literal>) that are never read again keep occupying
+ a slot until an eviction happens to pick them. If an application
+ stores large amounts of such one-shot data, give those entries a TTL
+ so they expire and can be recycled without displacing live entries,
+ or size the key pool for the full key set.
+ </simpara>
+ </section>
+
+ <section xml:id="yac.memory-values" annotations="chunk:false">
+ <title>The value pool (segments)</title>
+ <simpara>
+ <link linkend="ini.yac.values-memory-size">yac.values_memory_size</link>
+ is split into segments of 4M each, managed as rings: writes advance a
+ per-segment cursor and space is never freed per entry. When an
+ allocation no longer fits, the cursor wraps back to the start of a
+ segment — one <literal>recycle</literal> (the
+ <literal>recycles</literal> counter of
+ <methodname>Yac::info</methodname>). A recycle does not invalidate
+ the segment at once: overwritten values stay readable until the
+ wrapped cursor actually overwrites them, at which point their reads
+ fail the integrity guard and turn into misses.
+ </simpara>
+ <simpara>
+ Two sizes matter for this pool: the total
+ <link linkend="ini.yac.values-memory-size">yac.values_memory_size</link>
+ must hold the working set of live values, and a single entry can
+ hold at most 1 MB as stored
+ (<constant>YAC_MAX_RAW_COMPRESSED_LEN</constant>). Values larger
+ than that are therefore always compressed before being stored; a
+ value that cannot shrink below 1 MB — most often because it is
+ random data — is rejected and bumps the
+ <literal>fails</literal> counter. The absolute size limit on the
+ value itself is much higher: serialized values above 64 MB
+ (<constant>YAC_MAX_VALUE_RAW_LEN</constant>, that is
+ <literal>(1 << 26) - 1</literal> bytes) are rejected
+ outright.
+ </simpara>
+ </section>
+
+ <section xml:id="yac.memory-tuning" annotations="chunk:false">
+ <title>Sizing and what to watch</title>
+ <simpara>
+ Start with the defaults and watch the counters of
+ <methodname>Yac::info</methodname> — they accumulate from
+ <literal>start_time</literal>, so compare two snapshots taken some
+ time apart:
+ </simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ hit rate healthy (say >= 90%): the cache is fine; nothing to do,
+ whatever the other counters show;
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ hit rate low and <literal>kicks</literal> climbing: the key pool is
+ too small for the key set — live entries get evicted before they are
+ re-read. Raise
+ <link linkend="ini.yac.keys-memory-size">yac.keys_memory_size</link>;
+ </simpara>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>recycles</literal> frequent: this is a real problem, not a
+ benign counter. A recycle means the value allocator has wrapped and is
+ about to overwrite entries — anything overwritten dies before it could
+ be re-read, so the bytes spent storing it were wasted and the hit rate
+ suffers. The value pool is too small for the volume of live data. In
+ order of impact:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ give entries a TTL. Values written with <literal>ttl = 0</literal>
+ stay live forever, so they keep occupying the pool and force the
+ cursor to wrap sooner. A TTL bounds how long each entry may live,
+ shrinking the live working set the pool has to hold;
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ raise
+ <link
linkend="ini.yac.values-memory-size">yac.values_memory_size</link>
+ so the pool holds the whole live value set (remember to budget
+ roughly twice the live footprint — a value only dies once the
+ cursor comes back around to overwrite it);
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ store less per entry: lower
+ <link
linkend="ini.yac.compress-threshold">yac.compress_threshold</link>
+ if it is set above the <literal>1024</literal> minimum, so large
+ payloads are compressed, and trim values that do not need to be
+ cached in full;
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <simpara>
+ <literal>fails</literal> growing: values that could not be stored,
+ most often a single value larger than the 1 MB stored-size limit
+ even after compression — split the value.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+</chapter>
+
+<!-- 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
+-->
diff --git a/reference/yac/yac/add.xml b/reference/yac/yac/add.xml
index 5025732e38fd..8da46466dc8e 100644
--- a/reference/yac/yac/add.xml
+++ b/reference/yac/yac/add.xml
@@ -11,7 +11,7 @@
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier>
<type>bool</type><methodname>Yac::add</methodname>
- <methodparam><type
class="union"><type>string</type><type>array</type></type><parameter>keys</parameter></methodparam>
+ <methodparam><type
class="union"><type>string</type><type>array</type></type><parameter>key</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
@@ -31,7 +31,7 @@
&reftitle.parameters;
<variablelist>
<varlistentry>
- <term><parameter>keys</parameter></term>
+ <term><parameter>key</parameter></term>
<listitem>
<simpara>
A <type>string</type> key, or an <type>array</type> of
@@ -45,7 +45,7 @@
<simpara>
The value to store. Every PHP type except <type>resource</type> can
be stored. Only used in the single-key form; when
- <parameter>keys</parameter> is an array, this argument is instead the
+ <parameter>key</parameter> is an array, this argument is instead the
optional <parameter>ttl</parameter>.
</simpara>
</listitem>
@@ -68,21 +68,6 @@
Returns &true; on success, &false; on failure. A store is also rejected
(returning &false;) when the key already exists and has not expired.
</simpara>
- <note>
- <para>
- Yac stores entries without locks. Under heavy contention a store can
- fail transiently; if the value must eventually be stored, retry:
- <programlisting role="php">
-<![CDATA[
-<?php
-while (!$yac->add("key", "value")) {
- // retry on transient failure
-}
-?>
-]]>
- </programlisting>
- </para>
- </note>
</refsect1>
<refsect1 role="examples">
@@ -96,11 +81,31 @@ $yac = new Yac();
var_dump($yac->add("foo", "bar")); // bool(true)
var_dump($yac->add("foo", "baz")); // bool(false): "foo"
already exists
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Adding an entry with a TTL</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
// ttl in seconds; 0 (the default) means the entry never expires
$yac->add("short-lived", "value", 5);
sleep(6);
var_dump($yac->get("short-lived")); // bool(false): expired
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Adding multiple entries at once</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
// store several key => value pairs with one call, with a ttl
$yac->add(array("a" => 1, "b" => 2), 60);
diff --git a/reference/yac/yac/delete.xml b/reference/yac/yac/delete.xml
index 68d3ad88a82f..524a958f4e1c 100644
--- a/reference/yac/yac/delete.xml
+++ b/reference/yac/yac/delete.xml
@@ -11,7 +11,7 @@
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier>
<type>bool</type><methodname>Yac::delete</methodname>
- <methodparam><type
class="union"><type>string</type><type>array</type></type><parameter>keys</parameter></methodparam>
+ <methodparam><type
class="union"><type>string</type><type>array</type></type><parameter>key</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>delay</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<simpara>
@@ -38,7 +38,7 @@
&reftitle.parameters;
<variablelist>
<varlistentry>
- <term><parameter>keys</parameter></term>
+ <term><parameter>key</parameter></term>
<listitem>
<simpara>
A <type>string</type> key, or an <type>array</type> of keys to be
@@ -96,13 +96,33 @@ var_dump($yac->delete("never")); // bool(false): was never
stored
var_dump($yac->info()["slots_used"]); // int(1)
print_r($yac->dump()); // "foo" is still listed; its ttl
// is in the past
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Delayed deletion</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
-// delayed deletion: keep the entry readable for 60 more seconds
+// keep the entry readable for 60 more seconds before it expires
$yac->set("tmp", "value");
var_dump($yac->delete("tmp", 60)); // bool(true)
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Deleting multiple keys at once</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+$yac->set("tmp", "value");
-// deleting several keys at once returns true only when every key
-// was present
+// returns true only when every key was present
var_dump($yac->delete(array("tmp", "nope"))); // bool(false):
"nope" missing
?>
]]>
diff --git a/reference/yac/yac/dump.xml b/reference/yac/yac/dump.xml
index afd8377297a9..68b3843b335f 100644
--- a/reference/yac/yac/dump.xml
+++ b/reference/yac/yac/dump.xml
@@ -134,8 +134,9 @@
<term><literal>hits</literal></term>
<listitem><simpara>
A per-entry hit counter, bumped on each successful
- <methodname>Yac::get</methodname>, reset when the entry is overwritten,
- deleted or expires (as of yac 2.4.0).
+ <methodname>Yac::get</methodname> and reset when the entry is
+ overwritten by a new <methodname>Yac::set</methodname> or
+ <methodname>Yac::add</methodname> (as of yac 2.4.0).
</simpara></listitem>
</varlistentry>
<varlistentry>
@@ -232,6 +233,11 @@ Array
<?php
$yac = new Yac();
+// fill the cache with 250 entries
+for ($i = 0; $i < 250; $i++) {
+ $yac->set("key$i", $i);
+}
+
$page_size = 100;
$page_num = 2;
diff --git a/reference/yac/yac/get.xml b/reference/yac/yac/get.xml
index 55ccf9cc72d4..fd8cd0548de4 100644
--- a/reference/yac/yac/get.xml
+++ b/reference/yac/yac/get.xml
@@ -11,7 +11,7 @@
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier>
<type>mixed</type><methodname>Yac::get</methodname>
- <methodparam><type
class="union"><type>string</type><type>array</type></type><parameter>keys</parameter></methodparam>
+ <methodparam><type
class="union"><type>string</type><type>array</type></type><parameter>key</parameter></methodparam>
<methodparam
choice="opt"><type>mixed</type><parameter>default</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<simpara>
@@ -23,7 +23,7 @@
&reftitle.parameters;
<variablelist>
<varlistentry>
- <term><parameter>keys</parameter></term>
+ <term><parameter>key</parameter></term>
<listitem>
<simpara>
A <type>string</type> key, or an <type>array</type> of keys.
@@ -80,6 +80,16 @@ $yac = new Yac();
$yac->set("foo", "bar");
var_dump($yac->get("foo")); // string(3) "bar"
var_dump($yac->get("missing")); // bool(false): a miss
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Telling a stored false apart from a miss</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
// a miss and a stored false are indistinguishable without a default;
// a sentinel default (available as of yac 2.4.0) tells them apart
@@ -88,9 +98,21 @@ var_dump($yac->get("flag")); // bool(false): the
stored value
var_dump($yac->get("missing", false)); // bool(false): a miss, same shape
var_dump($yac->get("flag", "__NONE__")); // bool(false): the stored value
var_dump($yac->get("missing", "__NONE__")); // string(8)
"__NONE__": a miss
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Getting multiple keys at once</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
-// with an array of keys, only the found keys are present in the result
+$yac->set("foo", "bar");
$yac->set("foo2", "bar2");
+
+// with an array of keys, only the found keys are present in the result
var_dump($yac->get(array("foo", "foo2", "missing")));
// array(2) { ["foo"]=> string(3) "bar" ["foo2"]=> string(4)
"bar2" }
?>
diff --git a/reference/yac/yac/info.xml b/reference/yac/yac/info.xml
index 8c4e9c3978e3..572c5fc14f4d 100644
--- a/reference/yac/yac/info.xml
+++ b/reference/yac/yac/info.xml
@@ -134,18 +134,18 @@ print_r($yac->info());
<![CDATA[
Array
(
- [memory_size] => 46137344
- [slots_memory_size] => 4194304
- [values_memory_size] => 41943040
+ [memory_size] => 75497472
+ [slots_memory_size] => 8388608
+ [values_memory_size] => 67108864
[segment_size] => 4194304
- [segment_num] => 10
+ [segment_num] => 16
[miss] => 0
[hits] => 0
[fails] => 0
[kicks] => 0
[recycles] => 0
[start_time] => 1725955200
- [slots_size] => 32768
+ [slots_size] => 65536
[slots_used] => 1
)
]]>
diff --git a/reference/yac/yac/set.xml b/reference/yac/yac/set.xml
index 5ab42a9e5822..c6d50eb6b02d 100644
--- a/reference/yac/yac/set.xml
+++ b/reference/yac/yac/set.xml
@@ -11,7 +11,7 @@
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier>
<type>bool</type><methodname>Yac::set</methodname>
- <methodparam><type
class="union"><type>string</type><type>array</type></type><parameter>keys</parameter></methodparam>
+ <methodparam><type
class="union"><type>string</type><type>array</type></type><parameter>key</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
@@ -30,7 +30,7 @@
&reftitle.parameters;
<variablelist>
<varlistentry>
- <term><parameter>keys</parameter></term>
+ <term><parameter>key</parameter></term>
<listitem>
<simpara>
A <type>string</type> key, or an <type>array</type> of
@@ -44,7 +44,7 @@
<simpara>
The value to store. Every PHP type except <type>resource</type> can
be stored. Only used in the single-key form; when
- <parameter>keys</parameter> is an array, this argument is instead the
+ <parameter>key</parameter> is an array, this argument is instead the
optional <parameter>ttl</parameter>.
</simpara>
</listitem>
@@ -79,11 +79,31 @@ $yac = new Yac();
$yac->set("foo", "bar"); // store a single value
$yac->set("foo", "baz"); // overwrite the existing entry
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Setting an entry with a TTL</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
// ttl in seconds: the entry expires after 5 seconds
$yac->set("short-lived", "value", 5);
sleep(6);
var_dump($yac->get("short-lived")); // bool(false): expired
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Setting multiple entries at once</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
// store several key => value pairs with one call
$yac->set(array("a" => 1, "b" => 2));