[doc-en] master: ext/yac: Add a Memory Management chapter and improve the examples (#5822)

From: 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 &lt;&lt; 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 &lt;&lt; 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 &gt;= 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));

« previous php.doc.cvs (#23694) next »