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)

Author: laruence

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;

reference/yac/configure.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>

reference/yac/constants.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>