[DOC-CVS] [doc-en] master: Revise the Yac extension documentation (#5794)
[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-26T11:55:09+02:00
Commit: https://github.com/php/doc-en/commit/1a42637cd40d0f75af1435ff051c7caa9b1c83e0
Raw diff: https://github.com/php/doc-en/commit/1a42637cd40d0f75af1435ff051c7caa9b1c83e0.diff
Revise the Yac extension documentation (#5794)
* Revise the Yac extension documentation
- book: rewrite the introduction to state the lock-free semantics and
suitability boundaries; ini: document default values for every entry;
versions: add the yac 2.4.0 records
- Fix method signatures against the extension source: get() takes
string|array $keys plus an optional mixed $default (the old &$cas
parameter never existed), delete() takes $delay, set() returns bool
- Expand the examples on all ten method pages so every parameter is
exercised, and add See Also cross-references
- setup: document the --with-system-lz4 configure option, the
serializer configure switches and the GitHub repository
* Fix docbook-cs style violations
- Convert inline-only <para> elements to <simpara> as required by the
docbook-cs linter
- Use <exceptionname> for the Exception in Yac::__construct instead of
<classname>
* ini: convert the nested compress_threshold description to simpara
Changed paths:
M reference/yac/book.xml
M reference/yac/ini.xml
M reference/yac/setup.xml
M reference/yac/versions.xml
M reference/yac/yac/add.xml
M reference/yac/yac/construct.xml
M reference/yac/yac/delete.xml
M reference/yac/yac/dump.xml
M reference/yac/yac/flush.xml
M reference/yac/yac/get.xml
M reference/yac/yac/getter.xml
M reference/yac/yac/info.xml
M reference/yac/yac/set.xml
M reference/yac/yac/setter.xml
Diff:
diff --git a/reference/yac/book.xml b/reference/yac/book.xml
index 450d4a32bb6a..2263f2fe3490 100644
--- a/reference/yac/book.xml
+++ b/reference/yac/book.xml
@@ -8,9 +8,32 @@
<preface xml:id="intro.yac">
&reftitle.intro;
- <para>
- Yac (Yet Another cache), is a lock-free, shared memory user data cache, could be used to replace APC, local memcache.
- </para>
+ <simpara>
+ Yac (Yet Another Cache) is a lock-free, shared memory user data cache,
+ and can be used to replace APC or local memcached.
+ </simpara>
+ <simpara>
+ Yac stores data in shared memory, which makes it visible to every PHP
+ worker of the same machine without any inter-process communication.
+ Instead of locking, Yac relies on atomic slot updates plus a few
+ collision probes, so a cache miss never blocks a request, and a
+ concurrent write can at worst cause a failed store or a missed read
+ that the caller can simply retry.
+ </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
+ recreate: page fragments, configuration snapshots, small service
+ responses, and other local caches. It should not be used as the
+ authoritative store for irreplaceable data.
+ </simpara>
+ <note>
+ <simpara>
+ Shared memory is only visible within one machine. To share a cache
+ across several servers, use a network cache such as Memcached or
+ Redis instead.
+ </simpara>
+ </note>
</preface>
&reference.yac.setup;
diff --git a/reference/yac/ini.xml b/reference/yac/ini.xml
index d1ed592e4f21..c9bf9f9551ba 100644
--- a/reference/yac/ini.xml
+++ b/reference/yac/ini.xml
@@ -74,9 +74,13 @@
<type>int</type>
</term>
<listitem>
- <para>
-
- </para>
+ <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.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.yac.debug">
@@ -85,9 +89,10 @@
<type>int</type>
</term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ Reserved for debugging. As of Yac 2.4.0 this directive is
+ registered but has no effect.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.yac.enable">
@@ -96,9 +101,10 @@
<type>int</type>
</term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ Whether Yac is enabled. If disabled, creating a
+ <classname>Yac</classname> instance throws an exception.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.yac.enable-cli">
@@ -107,9 +113,12 @@
<type>int</type>
</term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ Whether Yac is enabled when running under the
+ <literal>CLI</literal> SAPI. It is disabled by default because
+ command line scripts usually start and stop immediately, and the
+ shared memory segment would be created for nothing.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.yac.keys-memory-size">
@@ -118,9 +127,14 @@
<type>string</type>
</term>
<listitem>
- <para>
-
- </para>
+ <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>.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.yac.serializer">
@@ -129,9 +143,16 @@
<type>string</type>
</term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ Serializer used to turn arbitrary PHP values into bytes before
+ storing them. Allowed values are <literal>php</literal> (the
+ default), <literal>json</literal>, <literal>igbinary</literal> and
+ <literal>msgpack</literal>. The latter three require the extension
+ to be built with the corresponding support. Binary serializers such
+ as <literal>igbinary</literal> and <literal>msgpack</literal> are
+ typically faster and produce smaller payloads than
+ <literal>php</literal>.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.yac.values-memory-size">
@@ -140,9 +161,13 @@
<type>string</type>
</term>
<listitem>
- <para>
-
- </para>
+ <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>
diff --git a/reference/yac/setup.xml b/reference/yac/setup.xml
index 80663956a4b1..19fa20e03691 100644
--- a/reference/yac/setup.xml
+++ b/reference/yac/setup.xml
@@ -6,24 +6,59 @@
<section xml:id="yac.requirements">
&reftitle.required;
- <para>
-
- </para>
+ <simpara>
+ No external library is required.
+ </simpara>
</section>
<!-- {{{ Installation -->
<section xml:id="yac.installation">
&reftitle.install;
- <para>
+ <simpara>
&pecl.moved;
- </para>
- <para>
+ </simpara>
+ <simpara>
&pecl.info;
<link xlink:href="&url.pecl.package;yac">&url.pecl.package;yac</link>.
- </para>
- <para>
+ </simpara>
+ <simpara>
&pecl.windows.download.avail;
+ </simpara>
+ <para>
+ The source code is hosted on
+ <link xlink:href="&url.git.hub;laruence/yac">GitHub</link>. To build the
+ extension from source:
+ <screen>
+<![CDATA[
+$ git clone https://github.com/laruence/yac.git
+$ cd yac
+$ phpize
+$ ./configure
+$ make
+$ sudo make install
+]]>
+ </screen>
</para>
+ <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
+ <option role="configure">--with-system-lz4</option> switch, which
+ requires the <literal>lz4.h</literal> header and
+ <literal>liblz4</literal> to be installed.
+ </simpara>
+ <simpara>
+ Alternative serializers can be compiled in with
+ <option role="configure">--enable-json</option>,
+ <option role="configure">--enable-msgpack</option> or
+ <option role="configure">--enable-igbinary</option>, which register the
+ corresponding extension as an optional dependency. The serializer used at
+ runtime is selected with the
+ <link linkend="ini.yac.serializer">yac.serializer</link> ini directive.
+ </simpara>
</section>
<!-- }}} -->
@@ -33,9 +68,9 @@
<section xml:id="yac.resources">
&reftitle.resources;
- <para>
-
- </para>
+ <simpara>
+ This extension does not define any resources.
+ </simpara>
</section>
</chapter>
diff --git a/reference/yac/versions.xml b/reference/yac/versions.xml
index c4d8a23cf8f5..2581df47f0b9 100644
--- a/reference/yac/versions.xml
+++ b/reference/yac/versions.xml
@@ -7,14 +7,27 @@
<function name='yac' from='PECL yac >= 1.0.0'/>
<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'/>
+ <function name='yac::add value' from='PECL yac >= 1.0.0'/>
+ <function name='yac::add ttl' from='PECL yac >= 1.0.0'/>
<function name='yac::set' from='PECL yac >= 1.0.0'/>
+ <function name='yac::set key' from='PECL yac >= 1.0.0'/>
+ <function name='yac::set value' from='PECL yac >= 1.0.0'/>
+ <function name='yac::set ttl' from='PECL yac >= 1.0.0'/>
<function name='yac::__set' from='PECL yac >= 1.0.0'/>
<function name='yac::get' from='PECL yac >= 1.0.0'/>
+ <function name='yac::get key' from='PECL yac >= 1.0.0'/>
+ <function name='yac::get cas' from='PECL yac >= 1.0.0, <= 2.3.1'/>
+ <function name='yac::get default' from='PECL yac >= 2.4.0'/>
<function name='yac::__get' from='PECL yac >= 1.0.0'/>
<function name='yac::delete' from='PECL yac >= 1.0.0'/>
+ <function name='yac::delete key' from='PECL yac >= 1.0.0'/>
+ <function name='yac::delete delay' from='PECL yac >= 1.0.0'/>
<function name='yac::flush' from='PECL yac >= 1.0.0'/>
<function name='yac::info' from='PECL yac >= 1.0.0'/>
<function name='yac::dump' from='PECL yac >= 1.0.0'/>
+ <function name='yac::dump limit' from='PECL yac >= 1.0.0'/>
+ <function name='yac::dump offset' from='PECL yac >= 2.4.0'/>
</versions>
<!-- Keep this comment at the end of the file
diff --git a/reference/yac/yac/add.xml b/reference/yac/yac/add.xml
index 97370866a40b..5025732e38fd 100644
--- a/reference/yac/yac/add.xml
+++ b/reference/yac/yac/add.xml
@@ -4,24 +4,27 @@
<refentry xml:id="yac.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Yac::add</refname>
- <refpurpose>Store into cache</refpurpose>
+ <refpurpose>Store a value without overwriting an existing one</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>Yac::add</methodname>
- <methodparam><type>string</type><parameter>keys</parameter></methodparam>
+ <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>keys</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>Yac::add</methodname>
- <methodparam><type>array</type><parameter>key_vals</parameter></methodparam>
+ <methodparam><type>array</type><parameter>values</parameter></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
- <para>
- Added a item into cache.
- </para>
+ <simpara>
+ Stores a value in the cache. Unlike <methodname>Yac::set</methodname>,
+ it does not overwrite an existing entry that is still valid; the store
+ is rejected in that case.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -30,25 +33,30 @@
<varlistentry>
<term><parameter>keys</parameter></term>
<listitem>
- <para>
- &string; key
- </para>
+ <simpara>
+ A <type>string</type> key, or an <type>array</type> of
+ <literal>key => value</literal> pairs to store in one call.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
- <para>
- mixed value, All php value type could be stored except &resource;
- </para>
+ <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
+ optional <parameter>ttl</parameter>.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ttl</parameter></term>
<listitem>
- <para>
- expire time
- </para>
+ <simpara>
+ Time to live in seconds. <literal>0</literal> means the entry never
+ expires by time.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -56,26 +64,63 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
+ <simpara>
+ 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">
+ &reftitle.examples;
+ <example>
+ <title><methodname>Yac::add</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+
+var_dump($yac->add("foo", "bar")); // bool(true)
+var_dump($yac->add("foo", "baz")); // bool(false): "foo" already exists
+
+// 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
+
+// store several key => value pairs with one call, with a ttl
+$yac->add(array("a" => 1, "b" => 2), 60);
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- &boolean;, &true; on success, &false; on failure
- <note>
- <para>
- <methodname>Yac::add</methodname> may fail if cas lock could not obtain,
- so, if you need the value to be stored properly, you may write codes like:
- <example>
- <title>Make sure the item is stored</title>
- <programlisting role="php">
- <![CDATA[
- while(!$yac->set("key", "value"));
- ]]>
- </programlisting>
- </example>
- </para>
- </note>
+ <simplelist>
+ <member><methodname>Yac::set</methodname></member>
+ <member><methodname>Yac::get</methodname></member>
+ <member><methodname>Yac::delete</methodname></member>
+ </simplelist>
</para>
</refsect1>
-
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/yac/yac/construct.xml b/reference/yac/yac/construct.xml
index fc414bbe76cf..87b4a3e6d589 100644
--- a/reference/yac/yac/construct.xml
+++ b/reference/yac/yac/construct.xml
@@ -13,10 +13,12 @@
<modifier>public</modifier> <methodname>Yac::__construct</methodname>
<methodparam choice="opt"><type>string</type><parameter>prefix</parameter><initializer>""</initializer></methodparam>
</constructorsynopsis>
- <para>
- prefix is used to prepended to keys, this could be used to avoiding conflicts between apps.
- </para>
-
+ <simpara>
+ Creates a new <classname>Yac</classname> instance. The optional
+ <parameter>prefix</parameter> is prepended to every key this instance stores,
+ which lets several applications or caches on the same machine use
+ overlapping key names without colliding.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -25,31 +27,49 @@
<varlistentry>
<term><parameter>prefix</parameter></term>
<listitem>
- <para>
- &string; prefix
- </para>
+ <simpara>
+ A key prefix, up to 48 bytes (<constant>YAC_MAX_KEY_LEN</constant>).
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
- <!-- Return values commented out, as constructors generally don't return a
- value. Uncomment this if you do need a return values section (for
- example, because there's also a procedural version of the method).
- <refsect1 role="returnvalues">
- &reftitle.returnvalues;
- <para>
-
- </para>
- </refsect1>
- -->
-
<refsect1 role="errors">
&reftitle.errors;
+ <simpara>
+ Throws an <exceptionname>Exception</exceptionname> if the cache is disabled
+ (<literal>yac.enable=0</literal>), or if <parameter>prefix</parameter> is
+ longer than 48 bytes.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>Yac::__construct</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+$yac->set("foo", "bar");
+
+$other = new Yac("app2_");
+var_dump($other->get("foo")); // bool(false): different namespace
+$other->set("foo", "baz"); // stored as "app2_foo"
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- Throws an <classname>Exception</classname> if Yac is not enabled. Throws
- <classname>Exception</classname> if <parameter>prefix</parameter> exceeds
- max key length of 48 (<constant>YAC_MAX_KEY_LEN</constant>) bytes.
+ <simplelist>
+ <member><methodname>Yac::set</methodname></member>
+ <member><methodname>Yac::get</methodname></member>
+ </simplelist>
</para>
</refsect1>
diff --git a/reference/yac/yac/delete.xml b/reference/yac/yac/delete.xml
index bd295f3fb1f3..0f9d02948826 100644
--- a/reference/yac/yac/delete.xml
+++ b/reference/yac/yac/delete.xml
@@ -12,11 +12,11 @@
<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 choice="opt"><type>int</type><parameter>ttl</parameter></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter>delay</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
- <para>
- remove items from cache
- </para>
+ <simpara>
+ Removes one or more items from the cache.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -25,17 +25,21 @@
<varlistentry>
<term><parameter>keys</parameter></term>
<listitem>
- <para>
- string key, or array of multiple keys to be removed
- </para>
+ <simpara>
+ A <type>string</type> key, or an <type>array</type> of keys to be
+ removed.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
- <term><parameter>ttl</parameter></term>
+ <term><parameter>delay</parameter></term>
<listitem>
- <para>
- if delay is set, delete will mark the items to be invalid in ttl second.
- </para>
+ <simpara>
+ Number of seconds before the item becomes invalid. When omitted or
+ <literal>0</literal>, the item is invalidated immediately. A positive
+ value keeps the item readable for that many seconds before it
+ expires.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -43,12 +47,48 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
+ <simpara>
+ Returns &true; on success, or &false; if the key was not present in
+ the cache.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>Yac::delete</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+$yac->set("foo", "bar");
+
+var_dump($yac->delete("foo")); // bool(true)
+var_dump($yac->delete("foo")); // bool(false): already gone
+
+// delayed deletion: keep the entry readable for 60 more seconds,
+// it disappears only after that time has passed
+$yac->set("tmp", "value");
+var_dump($yac->delete("tmp", 60)); // bool(true)
+
+// delete several keys at once
+var_dump($yac->delete(array("a", "b")));
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
-
+ <simplelist>
+ <member><methodname>Yac::set</methodname></member>
+ <member><methodname>Yac::flush</methodname></member>
+ </simplelist>
</para>
</refsect1>
-
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/yac/yac/dump.xml b/reference/yac/yac/dump.xml
index 8a8a4fc73a3a..5c913aaa3fbd 100644
--- a/reference/yac/yac/dump.xml
+++ b/reference/yac/yac/dump.xml
@@ -4,29 +4,41 @@
<refentry xml:id="yac.dump" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Yac::dump</refname>
- <refpurpose>Dump cache</refpurpose>
+ <refpurpose>Dump cache entries for inspection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
- <modifier>public</modifier> <type>mixed</type><methodname>Yac::dump</methodname>
- <methodparam><type>int</type><parameter>num</parameter></methodparam>
+ <modifier>public</modifier> <type>array</type><methodname>Yac::dump</methodname>
+ <methodparam choice="opt"><type>int</type><parameter>limit</parameter><initializer>100</initializer></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
- <para>
- Dump values stored in cache
- </para>
+ <simpara>
+ Dumps metadata of the entries currently stored in the cache. The
+ values themselves are not returned.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
- <term><parameter>num</parameter></term>
+ <term><parameter>limit</parameter></term>
+ <listitem>
+ <simpara>
+ Maximum number of entries to return.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>offset</parameter></term>
<listitem>
- <para>
- Maximum number of items should be returned
- </para>
+ <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>.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -34,12 +46,216 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
+ <simpara>
+ An <type>array</type> with one element per dumped entry. Each element
+ is itself an array describing the entry:
+ </simpara>
+ <variablelist>
+ <varlistentry>
+ <term><literal>index</literal></term>
+ <listitem><simpara>
+ The slot index of the entry in the hash table.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>hash</literal></term>
+ <listitem><simpara>
+ The 64-bit hash of the key, used for slot probing.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>crc</literal></term>
+ <listitem><simpara>
+ The CRC32 checksum of the stored value, used to detect torn reads.
+ <literal>0</literal> for embedded entries, which have no value block.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ttl</literal></term>
+ <listitem><simpara>
+ The expiration timestamp (Unix time). <literal>0</literal> means the
+ entry never expires by time. Note that
+ <methodname>Yac::delete</methodname> only marks an entry expired, so
+ deleted entries can still show up in the dump; a non-zero
+ <literal>ttl</literal> in the past indicates an expired or deleted
+ entry.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>k_len</literal></term>
+ <listitem><simpara>
+ The length of the key, in bytes.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>v_len</literal></term>
+ <listitem><simpara>
+ The length of the value, in bytes. For compressed entries this is the
+ length of the <emphasis>original</emphasis> value before compression
+ (as of yac 2.4.0; earlier versions reported the stored, compressed
+ length).
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>c_len</literal></term>
+ <listitem><simpara>
+ Only present for compressed entries (as of yac 2.4.0): the length of
+ the compressed payload actually stored in shared memory, in bytes.
+ Comparing <literal>c_len</literal> with <literal>v_len</literal> shows
+ how much compression saves per entry.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>size</literal></term>
+ <listitem><simpara>
+ The allocated size of the value block in shared memory, in bytes.
+ <literal>0</literal> for embedded entries.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>atime</literal></term>
+ <listitem><simpara>
+ The last access time (Unix time), updated on each successful
+ <methodname>Yac::get</methodname>. When the cache is full, the entry
+ with the oldest <literal>atime</literal> among the candidate slots is
+ evicted first (as of yac 2.4.0).
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <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).
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>embedded</literal></term>
+ <listitem><simpara>
+ Whether the value is stored directly inside the slot instead of in a
+ separate value block (as of yac 2.4.0). Small values —
+ <constant>NULL</constant>, booleans, small integers, strings of up to
+ 7 bytes and empty arrays — are embedded this way and allocate no value
+ memory at all; for them <literal>crc</literal> and
+ <literal>size</literal> are reported as <literal>0</literal>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>key</literal></term>
+ <listitem><simpara>
+ The cache key, without any instance prefix.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>Yac::dump</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+$yac->set("foo", "bar");
+$yac->set("baz", "qux");
+
+print_r($yac->dump());
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+Array
+(
+ [0] => Array
+ (
+ [index] => 12345
+ [hash] => 14463105906481965911
+ [crc] => 0
+ [ttl] => 0
+ [k_len] => 3
+ [v_len] => 3
+ [size] => 0
+ [atime] => 1725955200
+ [hits] => 0
+ [embedded] => 1
+ [key] => foo
+ )
+
+ [1] => Array
+ (
+ [index] => 12987
+ [hash] => 15132029420525657053
+ [crc] => 0
+ [ttl] => 0
+ [k_len] => 3
+ [v_len] => 3
+ [size] => 0
+ [atime] => 1725955200
+ [hits] => 0
+ [embedded] => 1
+ [key] => baz
+ )
+
+)
+]]>
+ </screen>
+ <simpara>
+ Entries are listed in slot order, not in the order they were stored.
+ Embedded entries (short scalars kept inside the slot itself) have
+ <literal>crc</literal> and <literal>size</literal> set to zero; entries
+ stored in a separate value block carry their checksum and block size,
+ and compressed entries additionally carry <literal>c_len</literal>.
+ </simpara>
+ </example>
+ <example>
+ <title>Paging through a large cache</title>
+ <simpara>
+ <parameter>limit</parameter> bounds how many entries a single call returns,
+ and <parameter>offset</parameter> skips that many entries before collecting,
+ so the two can be combined to page through a cache that holds more
+ entries than one call may return.
+ </simpara>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+
+$page_size = 100;
+$page_num = 2;
+
+// skip the first 100 entries and return the next 100 (page 2)
+$page = $yac->dump($page_size, $page_size * ($page_num - 1));
+
+var_dump(count($page));
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+int(100)
+]]>
+ </screen>
+ <simpara>
+ Fewer entries than requested are returned when the cache holds fewer
+ entries than the requested page covers, and an empty array is returned
+ once the offset points past the last occupied slot.
+ </simpara>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- mixed
+ <simplelist>
+ <member><methodname>Yac::info</methodname></member>
+ </simplelist>
</para>
</refsect1>
-
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/yac/yac/flush.xml b/reference/yac/yac/flush.xml
index cfb67a0c39d8..8204479396c2 100644
--- a/reference/yac/yac/flush.xml
+++ b/reference/yac/yac/flush.xml
@@ -13,9 +13,12 @@
<modifier>public</modifier> <type>bool</type><methodname>Yac::flush</methodname>
<void />
</methodsynopsis>
- <para>
- Remove all cached values
- </para>
+ <simpara>
+ Removes all cached values. Because the cache is shared by every
+ process of the same machine, this empties the cache globally; the
+ key prefix given to <methodname>Yac::__construct</methodname> does
+ not limit what gets flushed.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -25,12 +28,46 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
+ <simpara>
+ Returns &true;.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>Yac::flush</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+$yac->set("foo", "bar");
+
+$other = new Yac("app2_");
+$other->set("baz", "qux");
+
+// flush empties the whole cache: entries of every instance,
+// regardless of the prefix used when they were stored
+$yac->flush();
+
+var_dump($yac->get("foo")); // bool(false)
+var_dump($other->get("baz")); // bool(false)
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- bool, always true
+ <simplelist>
+ <member><methodname>Yac::delete</methodname></member>
+ <member><methodname>Yac::info</methodname></member>
+ </simplelist>
</para>
</refsect1>
-
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/yac/yac/get.xml b/reference/yac/yac/get.xml
index a6aeca0761c0..55ccf9cc72d4 100644
--- a/reference/yac/yac/get.xml
+++ b/reference/yac/yac/get.xml
@@ -11,31 +11,41 @@
&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>key</parameter></methodparam>
- <methodparam choice="opt"><type>int</type><parameter role="reference">cas</parameter><initializer>&null;</initializer></methodparam>
+ <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>keys</parameter></methodparam>
+ <methodparam choice="opt"><type>mixed</type><parameter>default</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
- <para>
+ <simpara>
Retrieve values from cache
- </para>
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
- <term><parameter>key</parameter></term>
+ <term><parameter>keys</parameter></term>
<listitem>
- <para>
- &string; keys, or &array; of multiple keys.
- </para>
+ <simpara>
+ A <type>string</type> key, or an <type>array</type> of keys.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
- <term><parameter>cas</parameter></term>
+ <term><parameter>default</parameter></term>
<listitem>
- <para>
- if not &null;, it will be set to the retrieved item's cas.
- </para>
+ <simpara>
+ The value to return when the requested key (or keys) is not
+ present in the cache, available as of yac 2.4.0. When omitted, a
+ miss returns &false;.
+ </simpara>
+ <note>
+ <simpara>
+ Before yac 2.4.0, this argument slot held a by-reference
+ <literal>$cas</literal> token rather than a default value. Code
+ that passed or relied on that token must be updated when
+ upgrading to 2.4.0.
+ </simpara>
+ </note>
</listitem>
</varlistentry>
</variablelist>
@@ -43,12 +53,62 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
+ <simpara>
+ For a <type>string</type> key, returns the cached value on a hit,
+ otherwise the <parameter>default</parameter> (or &false; when no default
+ was given).
+ </simpara>
+ <simpara>
+ For an <type>array</type> of keys, returns an array containing the
+ found values indexed by their keys. Keys that are not present in
+ the cache are omitted from the result as of yac 2.4.0, or filled
+ with the <parameter>default</parameter> when one was given; before
+ 2.4.0, a &false; placeholder was inserted for every missing key.
+ </simpara>
+ </refsect1>
+
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>Yac::get</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+
+$yac->set("foo", "bar");
+var_dump($yac->get("foo")); // string(3) "bar"
+var_dump($yac->get("missing")); // bool(false): a miss
+
+// a miss and a stored false are indistinguishable without a default;
+// a sentinel default (available as of yac 2.4.0) tells them apart
+$yac->set("flag", false);
+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
+
+// with an array of keys, only the found keys are present in the result
+$yac->set("foo2", "bar2");
+var_dump($yac->get(array("foo", "foo2", "missing")));
+// array(2) { ["foo"]=> string(3) "bar" ["foo2"]=> string(4) "bar2" }
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- mixed on success, false on failure
+ <simplelist>
+ <member><methodname>Yac::set</methodname></member>
+ <member><methodname>Yac::__get</methodname></member>
+ </simplelist>
</para>
</refsect1>
-
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/yac/yac/getter.xml b/reference/yac/yac/getter.xml
index b35e62d71de8..524758760392 100644
--- a/reference/yac/yac/getter.xml
+++ b/reference/yac/yac/getter.xml
@@ -4,7 +4,7 @@
<refentry xml:id="yac.getter" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Yac::__get</refname>
- <refpurpose>Getter</refpurpose>
+ <refpurpose>Retrieve a value using property syntax</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -13,9 +13,11 @@
<modifier>public</modifier> <type>mixed</type><methodname>Yac::__get</methodname>
<methodparam><type>string</type><parameter>key</parameter></methodparam>
</methodsynopsis>
- <para>
- Retrieve values from cache
- </para>
+ <simpara>
+ Retrieves a value from the cache, invoked when reading a property of a
+ <classname>Yac</classname> instance: <literal>$yac->foo</literal> is
+ equivalent to <literal>$yac->get("foo")</literal>.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -24,9 +26,9 @@
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
- <para>
- &string; key
- </para>
+ <simpara>
+ The property name, used as the cache key.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -34,12 +36,47 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
+ <simpara>
+ The cached value on a hit, &null; when the key is not present in the
+ cache.
+ </simpara>
+ <note>
+ <simpara>
+ Unlike <methodname>Yac::get</methodname>, property syntax cannot
+ distinguish a stored &null; from a missing key, and only supports
+ single keys.
+ </simpara>
+ </note>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>Yac::__get</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+$yac->set("foo", "bar");
+
+var_dump($yac->foo); // string(3) "bar"
+var_dump($yac->missing); // NULL
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- mixed on success, &null; on failure
+ <simplelist>
+ <member><methodname>Yac::get</methodname></member>
+ <member><methodname>Yac::__set</methodname></member>
+ </simplelist>
</para>
</refsect1>
-
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/yac/yac/info.xml b/reference/yac/yac/info.xml
index 4d682b589ab2..8c4e9c3978e3 100644
--- a/reference/yac/yac/info.xml
+++ b/reference/yac/yac/info.xml
@@ -13,9 +13,9 @@
<modifier>public</modifier> <type>array</type><methodname>Yac::info</methodname>
<void />
</methodsynopsis>
- <para>
+ <simpara>
Get status of cache system
- </para>
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -25,14 +25,148 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
+ <simpara>
+ Returns an <type>array</type> with the following keys:
+ </simpara>
+ <variablelist>
+ <varlistentry>
+ <term><literal>memory_size</literal></term>
+ <listitem><simpara>
+ Total shared memory in use, in bytes: the slot table plus the value
+ blocks.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>slots_memory_size</literal></term>
+ <listitem><simpara>
+ Memory reserved for the hash slot table, in bytes.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>values_memory_size</literal></term>
+ <listitem><simpara>
+ Memory reserved for the stored values, in bytes.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>segment_size</literal></term>
+ <listitem><simpara>
+ Size of one value memory segment, in bytes.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>segment_num</literal></term>
+ <listitem><simpara>
+ Number of value memory segments.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>miss</literal></term>
+ <listitem><simpara>
+ Number of cache misses: lookups that found nothing or an expired
+ entry.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>hits</literal></term>
+ <listitem><simpara>
+ Number of cache hits: successful lookups.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>fails</literal></term>
+ <listitem><simpara>
+ Number of failed stores: stores that could not allocate a value
+ block.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>kicks</literal></term>
+ <listitem><simpara>
+ Number of evictions: how often an existing entry had to be evicted
+ because the candidate slot path was full.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>recycles</literal></term>
+ <listitem><simpara>
+ Number of times the allocator reached the end of a segment and
+ wrapped around to its beginning.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>start_time</literal></term>
+ <listitem><simpara>
+ The Unix timestamp at which the shared memory cache was initialized.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>slots_size</literal></term>
+ <listitem><simpara>
+ Total number of hash slots.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>slots_used</literal></term>
+ <listitem><simpara>
+ Number of hash slots currently occupied.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>Yac::info</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+$yac->set("foo", "bar");
+
+print_r($yac->info());
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+Array
+(
+ [memory_size] => 46137344
+ [slots_memory_size] => 4194304
+ [values_memory_size] => 41943040
+ [segment_size] => 4194304
+ [segment_num] => 10
+ [miss] => 0
+ [hits] => 0
+ [fails] => 0
+ [kicks] => 0
+ [recycles] => 0
+ [start_time] => 1725955200
+ [slots_size] => 32768
+ [slots_used] => 1
+)
+]]>
+ </screen>
+ <simpara>
+ The hit ratio can be computed as <literal>hits / (hits + miss)</literal>;
+ a growing <literal>kicks</literal> or <literal>fails</literal> counter
+ indicates that the cache is under memory pressure.
+ </simpara>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- Return an array, consistent with:
- "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num",
- "miss", "hits", "fails", "kicks", "recycles", "slots_size", "slots_used"
+ <simplelist>
+ <member><methodname>Yac::dump</methodname></member>
+ </simplelist>
</para>
</refsect1>
-
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/yac/yac/set.xml b/reference/yac/yac/set.xml
index ca782c2571af..5ab42a9e5822 100644
--- a/reference/yac/yac/set.xml
+++ b/reference/yac/yac/set.xml
@@ -4,24 +4,26 @@
<refentry xml:id="yac.set" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Yac::set</refname>
- <refpurpose>Store into cache</refpurpose>
+ <refpurpose>Store a value into the cache</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>Yac::set</methodname>
- <methodparam><type>string</type><parameter>keys</parameter></methodparam>
+ <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>keys</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<methodsynopsis>
- <modifier>public</modifier> <type>bool</type><methodname>Yac::add</methodname>
- <methodparam><type>array</type><parameter>key_vals</parameter></methodparam>
+ <modifier>public</modifier> <type>bool</type><methodname>Yac::set</methodname>
+ <methodparam><type>array</type><parameter>values</parameter></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
- <para>
- Add a item into cache, it the key is already exists, override it.
- </para>
+ <simpara>
+ Stores a value in the cache. If the key already exists, the existing
+ entry is overwritten, regardless of whether it has expired.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -30,25 +32,30 @@
<varlistentry>
<term><parameter>keys</parameter></term>
<listitem>
- <para>
- &string; key
- </para>
+ <simpara>
+ A <type>string</type> key, or an <type>array</type> of
+ <literal>key => value</literal> pairs to store in one call.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
- <para>
- mixed value, All php value type could be stored except &resource;
- </para>
+ <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
+ optional <parameter>ttl</parameter>.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ttl</parameter></term>
<listitem>
- <para>
- expire time
- </para>
+ <simpara>
+ Time to live in seconds. <literal>0</literal> means the entry never
+ expires by time.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -56,8 +63,44 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
+ <simpara>
+ Returns &true; on success, &false; on failure.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>Yac::set</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+
+$yac->set("foo", "bar"); // store a single value
+$yac->set("foo", "baz"); // overwrite the existing entry
+
+// 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
+
+// store several key => value pairs with one call
+$yac->set(array("a" => 1, "b" => 2));
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- the value self
+ <simplelist>
+ <member><methodname>Yac::add</methodname></member>
+ <member><methodname>Yac::get</methodname></member>
+ <member><methodname>Yac::__set</methodname></member>
+ </simplelist>
</para>
</refsect1>
diff --git a/reference/yac/yac/setter.xml b/reference/yac/yac/setter.xml
index cd41373f61b0..55227798d11a 100644
--- a/reference/yac/yac/setter.xml
+++ b/reference/yac/yac/setter.xml
@@ -4,38 +4,42 @@
<refentry xml:id="yac.setter" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Yac::__set</refname>
- <refpurpose>Setter</refpurpose>
+ <refpurpose>Store a value using property syntax</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>mixed</type><methodname>Yac::__set</methodname>
- <methodparam><type>string</type><parameter>keys</parameter></methodparam>
+ <methodparam><type>string</type><parameter>key</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
</methodsynopsis>
- <para>
- store a item into cache
- </para>
+ <simpara>
+ Stores a value in the cache, invoked when writing a property of a
+ <classname>Yac</classname> instance: <literal>$yac->foo = "bar"</literal>
+ is equivalent to <literal>$yac->set("foo", "bar")</literal>, with no
+ ttl.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
- <term><parameter>keys</parameter></term>
+ <term><parameter>key</parameter></term>
<listitem>
- <para>
- &string; key
- </para>
+ <simpara>
+ The property name, used as the cache key.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
- <para>
- mixed value, All php value type could be stored except &resource;
- </para>
+ <simpara>
+ The value to store. Every PHP type except <type>resource</type> can
+ be stored.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -43,8 +47,35 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
+ <simpara>
+ Returns the stored value.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>Yac::__set</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$yac = new Yac();
+
+$yac->foo = "bar"; // stored without a ttl
+var_dump($yac->get("foo")); // string(3) "bar"
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- Always return the value self
+ <simplelist>
+ <member><methodname>Yac::set</methodname></member>
+ <member><methodname>Yac::__get</methodname></member>
+ </simplelist>
</para>
</refsect1>