[DOC-CVS] [doc-en] master: Enhance the Yac extension documentation (#5810)
[email protected] (Xinchen Hui via GitHub)
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: Xinchen Hui (laruence)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-27T16:58:21+02:00
Commit: https://github.com/php/doc-en/commit/d3a03f8f542cd083d793bbd8ef3d7756aae7711f
Raw diff: https://github.com/php/doc-en/commit/d3a03f8f542cd083d793bbd8ef3d7756aae7711f.diff
Enhance the Yac extension documentation (#5810)
- Highlight the performance characteristics of the lock-free design and
document the embedded values and the LZ4 compression backend
introduced in yac 2.4.0 in the introduction
- Fill in the Yac class introduction and the _prefix property, and
describe the overloaded property access
- Document the deferred-expiry semantics of Yac::delete(): entries are
only marked expired, slots_used does not decrease, expired entries
still show up in the dump and must be filtered by the caller
- Document that Yac::dump() $offset is available as of 2.4.0, and that
passing -1 as $limit dumps all entries
- Document installing yac with PIE (as of 2.3.2) and the switch from
FastLZ to LZ4 in 2.4.0
Changed paths:
M reference/yac/book.xml
M reference/yac/setup.xml
M reference/yac/versions.xml
M reference/yac/yac.xml
M reference/yac/yac/delete.xml
M reference/yac/yac/dump.xml
Diff:
diff --git a/reference/yac/book.xml b/reference/yac/book.xml
index 2263f2fe3490..c0aba1418ee6 100644
--- a/reference/yac/book.xml
+++ b/reference/yac/book.xml
@@ -20,6 +20,13 @@
concurrent write can at worst cause a failed store or a missed read
that the caller can simply retry.
</simpara>
+ <simpara>
+ With no locks and no inter-process communication in the access
+ 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.
+ </simpara>
<simpara>
Because Yac trades correctness guarantees for speed and throughput,
it is best suited for data that is expensive to produce but easy to
@@ -27,6 +34,16 @@
responses, and other local caches. It should not be used as the
authoritative store for irreplaceable data.
</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
+ 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.
+ Version 2.4.0 also switched the compression backend from FastLZ to
+ LZ4, making compressed reads several times faster.
+ </simpara>
<note>
<simpara>
Shared memory is only visible within one machine. To share a cache
diff --git a/reference/yac/setup.xml b/reference/yac/setup.xml
index 19fa20e03691..4defe5047af7 100644
--- a/reference/yac/setup.xml
+++ b/reference/yac/setup.xml
@@ -14,6 +14,10 @@
<!-- {{{ Installation -->
<section xml:id="yac.installation">
&reftitle.install;
+ <simpara>
+ Yac can be installed in one of three ways: via PECL, via PIE, or
+ by building it from source.
+ </simpara>
<simpara>
&pecl.moved;
</simpara>
@@ -24,28 +28,64 @@
<simpara>
&pecl.windows.download.avail;
</simpara>
- <para>
+ <example>
+ <title>Installing Yac with PECL</title>
+ <programlisting role="shell">
+<![CDATA[
+pecl install yac
+]]>
+ </programlisting>
+ </example>
+ <simpara>
+ As of Yac 2.3.2, the extension can be installed with
+ &link.pie;, the PHP Installer for Extensions, by running the
+ following on the command line.
+ </simpara>
+ <example>
+ <title>Installing Yac with PIE</title>
+ <programlisting role="shell">
+<![CDATA[
+pie install laruence/yac
+]]>
+ </programlisting>
+ </example>
+ <simpara>
+ Optional serializers can be enabled at install time:
+ </simpara>
+ <example>
+ <title>Installing Yac with PIE and a serializer</title>
+ <programlisting role="shell">
+<![CDATA[
+pie install laruence/yac --enable-json
+]]>
+ </programlisting>
+ </example>
+ <simpara>
The source code is hosted on
- <link xlink:href="&url.git.hub;laruence/yac">GitHub</link>. To build the
- extension from source:
- <screen>
+ <link xlink:href="&url.git.hub;laruence/yac">GitHub</link>. To
+ build the extension from source, run the following on the command
+ line, replacing the paths with those of the local PHP
+ installation.
+ </simpara>
+ <example>
+ <title>Building Yac from source</title>
+ <programlisting role="shell">
<![CDATA[
-$ git clone https://github.com/laruence/yac.git
-$ cd yac
-$ phpize
-$ ./configure
-$ make
-$ sudo make install
+/path/to/phpize
+./configure --with-php-config=/path/to/php-config
+make && make install
]]>
- </screen>
- </para>
+ </programlisting>
+ </example>
<simpara>
The following <literal>configure</literal> options are available:
</simpara>
<simpara>
- Values are compressed with LZ4 before being stored. By default, Yac uses
- the LZ4 copy bundled with the extension; no extra flag is needed. To link
- against the system LZ4 library instead, use the
+ Values are compressed with LZ4 before being stored. The LZ4
+ compression backend was introduced in Yac 2.4.0, replacing the
+ earlier FastLZ. By default, Yac uses the LZ4 copy bundled with the
+ extension; no extra flag is needed. To link against the system LZ4
+ library instead, use the
<option role="configure">--with-system-lz4</option> switch, which
requires the <literal>lz4.h</literal> header and
<literal>liblz4</literal> to be installed.
diff --git a/reference/yac/versions.xml b/reference/yac/versions.xml
index 2581df47f0b9..afb0258b6387 100644
--- a/reference/yac/versions.xml
+++ b/reference/yac/versions.xml
@@ -5,6 +5,8 @@
<!-- Classes and Methods -->
<function name='yac' from='PECL yac >= 1.0.0'/>
+ <!-- 2.4.0: embedded values, compression backend switched to LZ4,
+ Yac::info start_time and per-entry hits; see RELEASE_NOTES -->
<function name='yac::__construct' from='PECL yac >= 1.0.0'/>
<function name='yac::add' from='PECL yac >= 1.0.0'/>
<function name='yac::add key' from='PECL yac >= 1.0.0'/>
diff --git a/reference/yac/yac.xml b/reference/yac/yac.xml
index 56a8879c646c..fe96750dda71 100644
--- a/reference/yac/yac.xml
+++ b/reference/yac/yac.xml
@@ -11,9 +11,27 @@
<!-- {{{ Yac intro -->
<section xml:id="yac.intro">
&reftitle.intro;
- <para>
-
- </para>
+ <simpara>
+ The <classname>Yac</classname> class is the interface to the cache.
+ Every instance on the same host is a lightweight handle to one
+ shared cache: all instances read and write the same entries, and
+ creating one does no allocation beyond the handle itself.
+ </simpara>
+ <simpara>
+ The optional prefix passed to
+ <methodname>Yac::__construct</methodname> is prepended to every
+ key, so several instances (or applications) can share one cache
+ without their keys colliding. Besides the classic cache operations
+ (<methodname>Yac::add</methodname>,
+ <methodname>Yac::set</methodname>,
+ <methodname>Yac::get</methodname>,
+ <methodname>Yac::delete</methodname> and
+ <methodname>Yac::flush</methodname>), the class provides
+ <methodname>Yac::info</methodname> and
+ <methodname>Yac::dump</methodname> for inspecting the cache, and
+ overloads property access so that reading or writing an object
+ property reads or writes a cache entry.
+ </simpara>
</section>
<!-- }}} -->
@@ -54,7 +72,13 @@
<varlistentry xml:id="yac.props.prefix">
<term><varname>_prefix</varname></term>
<listitem>
- <para></para>
+ <simpara>
+ The key prefix set through
+ <methodname>Yac::__construct</methodname>. It is prepended to
+ every key used with the instance; no separator is inserted, so
+ include one in the prefix when needed. The prefix may not exceed
+ <constant>YAC_MAX_KEY_LEN</constant> (48) bytes.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
diff --git a/reference/yac/yac/delete.xml b/reference/yac/yac/delete.xml
index 0f9d02948826..68d3ad88a82f 100644
--- a/reference/yac/yac/delete.xml
+++ b/reference/yac/yac/delete.xml
@@ -17,6 +17,21 @@
<simpara>
Removes one or more items from the cache.
</simpara>
+ <note>
+ <simpara>
+ Deletion is implemented by marking the entry expired rather than
+ clearing its slot: the entry immediately stops being readable, but
+ the slot stays occupied until the same key is stored again or a
+ later write reclaims the slot. As a result, the used-slot count
+ reported by <methodname>Yac::info</methodname> does not decrease
+ after a deletion, and <methodname>Yac::dump</methodname> still
+ lists the deleted entry until its slot is recycled; a non-zero
+ <literal>ttl</literal> in the past marks a deleted or expired
+ entry, so when inspecting the output of
+ <methodname>Yac::dump</methodname>, such entries have to be
+ filtered out by the caller.
+ </simpara>
+ </note>
</refsect1>
<refsect1 role="parameters">
@@ -49,7 +64,14 @@
&reftitle.returnvalues;
<simpara>
Returns &true; on success, or &false; if the key was not present in
- the cache.
+ the cache. Because a deletion only marks the entry expired, a key
+ that was deleted but not yet overwritten still counts as present:
+ deleting the same key again returns &true;.
+ </simpara>
+ <simpara>
+ When an <type>array</type> of keys is given, &true; is returned
+ only if every key was present; if any key is missing, &false; is
+ returned.
</simpara>
</refsect1>
@@ -63,16 +85,25 @@
$yac = new Yac();
$yac->set("foo", "bar");
-var_dump($yac->delete("foo")); // bool(true)
-var_dump($yac->delete("foo")); // bool(false): already gone
+var_dump($yac->delete("foo")); // bool(true): marked expired
+var_dump($yac->get("foo")); // bool(false): a miss from now on
+var_dump($yac->delete("foo")); // bool(true) again: the slot has not
+ // been overwritten yet
+var_dump($yac->delete("never")); // bool(false): was never stored
+
+// a deletion does not free the slot: slots_used does not drop, and
+// the expired entry still shows up in the dump
+var_dump($yac->info()["slots_used"]); // int(1)
+print_r($yac->dump()); // "foo" is still listed; its ttl
+ // is in the past
-// delayed deletion: keep the entry readable for 60 more seconds,
-// it disappears only after that time has passed
+// delayed deletion: keep the entry readable for 60 more seconds
$yac->set("tmp", "value");
-var_dump($yac->delete("tmp", 60)); // bool(true)
+var_dump($yac->delete("tmp", 60)); // bool(true)
-// delete several keys at once
-var_dump($yac->delete(array("a", "b")));
+// deleting several keys at once returns true only when every key
+// was present
+var_dump($yac->delete(array("tmp", "nope"))); // bool(false): "nope" missing
?>
]]>
</programlisting>
@@ -85,6 +116,8 @@ var_dump($yac->delete(array("a", "b")));
<simplelist>
<member><methodname>Yac::set</methodname></member>
<member><methodname>Yac::flush</methodname></member>
+ <member><methodname>Yac::info</methodname></member>
+ <member><methodname>Yac::dump</methodname></member>
</simplelist>
</para>
</refsect1>
diff --git a/reference/yac/yac/dump.xml b/reference/yac/yac/dump.xml
index 5c913aaa3fbd..afd8377297a9 100644
--- a/reference/yac/yac/dump.xml
+++ b/reference/yac/yac/dump.xml
@@ -29,15 +29,24 @@
<simpara>
Maximum number of entries to return.
</simpara>
+ <simpara>
+ Passing <literal>-1</literal> as <parameter>limit</parameter> dumps
+ every entry the cache currently holds. Note that building the
+ full list may use a considerable amount of memory for a large
+ cache; when memory matters, page through the entries with
+ <parameter>limit</parameter> and <parameter>offset</parameter> instead.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<simpara>
- Number of entries to skip before collecting, which can be used to
- page through a cache that holds more entries than
- <parameter>limit</parameter>.
+ Number of entries to skip before collecting. This parameter
+ is available as of PECL yac 2.4.0; earlier versions always
+ start from the first entry. Combined with
+ <parameter>limit</parameter>, it can be used to page through a
+ cache that holds more entries than one call may return.
</simpara>
</listitem>
</varlistentry>