新增 Yac 内存管理章节并同步 doc-en #5822 的文档更新

reference/yac/book.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: d3a03f8f542cd083d793bbd8ef3d7756aae7711f Maintainer: Laruence Status: ready -->
+<!-- EN-Revision: c05fbe7250c43b75034ac776ed78f4e67163e4d3 Maintainer: Laruence Status: ready -->
 
 <book xml:id="book.yac" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <?phpdoc extension-membership="pecl" ?>
@@ -10,48 +10,32 @@
  <preface xml:id="intro.yac">
   &reftitle.intro;
   <simpara>
-   Yac（Yet Another Cache）是一个无锁（lock-free）的共享内存用户数据缓存，
-   可以用来替代 APC 或本地 memcached。
+   Yac（Yet Another Cache）是一个无锁（lock-free）的共享内存用户数据缓存，可以用来替代 APC 或本地 memcached。
   </simpara>
   <simpara>
-   Yac 将数据存储在共享内存中，同一台机器上的每个 PHP 工作进程
-   都能直接访问，无需任何进程间通信。
-   Yac 不加锁，而是依靠原子的槽位更新加上少量的冲突探测，
-   因此缓存未命中（cache miss）绝不会阻塞请求；
-   并发写入最坏的情况也只是某次存储失败或某次读取落空，
-   调用方直接重试即可。
+   Yac 将数据存储在共享内存中，同一台机器上的每个 PHP 工作进程都能直接访问，无需任何进程间通信。
+   Yac 不加锁，而是依靠原子的槽位更新加上少量的冲突探测，因此缓存未命中（cache miss）绝不会阻塞请求；并发写入最坏的情况也只是某次存储失败或某次读取落空，调用方直接重试即可。
   </simpara>
   <simpara>
-   访问路径上没有锁，也没有进程间通信，一次读取本质上就是
-   在共享内存中做一次哈希查找。因此，Yac 极其快，
-   读取延迟在微秒级；只要写入分散在不同的键上，
-   吞吐量还能随着访问缓存的 worker 数量增长。
+   访问路径上没有锁，也没有进程间通信，一次读取本质上就是在共享内存中做一次哈希查找。因此，Yac 极其快，读取延迟在微秒级；只要写入分散在不同的键上，吞吐量还能随着访问缓存的 worker 数量增长；参见
+   <link xlink:href="&url.git.hub;laruence/yac/blob/master/README.md#benchmarks">基准测试</link>。
   </simpara>
   <simpara>
-   由于 Yac 用正确性保证换取速度和吞吐量，
-   它最适合缓存那些生成代价高但可以轻易重建的数据：
-   页面片段、配置快照、小型服务响应等本地缓存。
-   不要把它用作不可替代数据的权威存储。
+   由于 Yac 用正确性保证换取速度和吞吐量，它最适合缓存那些生成代价高但可以轻易重建的数据：页面片段、配置快照、小型服务响应等本地缓存。不要把它用作不可替代数据的权威存储。
   </simpara>
   <simpara>
-   从 yac 2.4.0 开始，小标量值——<constant>NULL</constant>、
-   布尔值、整数、最长 7 字节的短字符串和空数组——
-   直接存储在哈希槽（hash slot）里，而不是单独的值块
-   （即“嵌入值”，embedded values）。这样每次访问都省去了
-   值内存的分配和块拷贝，显著提升性能的同时减少了内存占用。
-   2.4.0 还把压缩后端从 FastLZ 换成了 LZ4，
-   使压缩数据的读取快了好几倍。
+   从 yac 2.4.0 开始，小标量值——<constant>NULL</constant>、布尔值、大多数整数（在 64 位构建下能装进 60 个有符号位的整数）、最长 7 字节的字符串和空数组——直接存储在哈希槽（hash slot）里，而不是单独的值块（即“嵌入值”，embedded values）。这样每次访问都省去了值内存的分配和块拷贝，显著提升性能的同时减少了内存占用。
+   2.4.0 还把压缩后端从 FastLZ 换成了 LZ4，使压缩数据的读取快了好几倍。
   </simpara>
   <note>
    <simpara>
-    共享内存仅在同一台机器内可见。
-    如果需要在多台服务器之间共享缓存，
-    请使用 Memcached 或 Redis 等网络缓存。
+    共享内存仅在同一台机器内可见。如果需要在多台服务器之间共享缓存，请使用 Memcached 或 Redis 等网络缓存。
    </simpara>
   </note>
  </preface>
 
  &reference.yac.setup;
+ &reference.yac.memory;
  &reference.yac.constants;
  <!-- &reference.yac.examples; -->
  &reference.yac.yac;

reference/yac/constants.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 86e6094e86b84a51d00ab217ac50ce8dde33d82a Maintainer: Laruence Status: ready -->
+<!-- EN-Revision: c05fbe7250c43b75034ac776ed78f4e67163e4d3 Maintainer: Laruence Status: ready -->
 
 <appendix xml:id="yac.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  &reftitle.constants;
@@ -14,6 +14,7 @@
     </term>
     <listitem>
      <simpara>
+      扩展的版本号（字符串形式）。
      </simpara>
     </listitem>
    </varlistentry>
@@ -24,7 +25,7 @@
     </term>
     <listitem>
      <simpara>
-      键允许的最大长度，为 48 字节。
+      键的最大长度，单位为字节：48。实例前缀也计入该限制。
      </simpara>
     </listitem>
    </varlistentry>
@@ -35,6 +36,8 @@
     </term>
     <listitem>
      <simpara>
+      值在序列化前的最大长度，单位为字节：
+      67,108,863（<literal>(1 &lt;&lt; 26) - 1</literal>）。更大的值会被拒绝。
      </simpara>
     </listitem>
    </varlistentry>
@@ -45,6 +48,7 @@
     </term>
     <listitem>
      <simpara>
+      存储条目的最大尺寸，单位为字节：1,048,576（1M）。压缩后仍放不下的值会被拒绝。
      </simpara>
     </listitem>
    </varlistentry>
@@ -55,7 +59,7 @@
     </term>
     <listitem>
      <simpara>
-      使用 PHP serialize 作为序列化器。
+      使用 PHP serialize 作为序列化器（默认）。
      </simpara>
     </listitem>
    </varlistentry>
@@ -66,7 +70,8 @@
     </term>
     <listitem>
      <simpara>
-      使用 JSON 作为序列化器（需要 --enable-json）。
+      使用 JSON 作为序列化器。需要扩展以
+      <option role="configure">--enable-json</option> 支持编译。
      </simpara>
     </listitem>
    </varlistentry>
@@ -77,7 +82,8 @@
     </term>
     <listitem>
      <simpara>
-      使用 igbinary 作为序列化器（需要 --enable-igbinary）。
+      使用 igbinary 作为序列化器。需要扩展以
+      <option role="configure">--enable-igbinary</option> 支持编译。
      </simpara>
     </listitem>
    </varlistentry>
@@ -88,7 +94,8 @@
     </term>
     <listitem>
      <simpara>
-      使用 msgpack 作为序列化器（需要 --enable-msgpack）。
+      使用 msgpack 作为序列化器。需要扩展以
+      <option role="configure">--enable-msgpack</option> 支持编译。
      </simpara>
     </listitem>
    </varlistentry>
@@ -99,7 +106,7 @@
     </term>
     <listitem>
      <simpara>
-      Yac 当前使用的序列化器。
+      扩展当前使用的序列化器。
      </simpara>
     </listitem>
    </varlistentry>

reference/yac/ini.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 1a42637cd40d0f75af1435ff051c7caa9b1c83e0 Maintainer: Laruence Status: ready -->
+<!-- EN-Revision: c05fbe7250c43b75034ac776ed78f4e67163e4d3 Maintainer: Laruence Status: ready -->
 
 <section xml:id="yac.configuration" xmlns="http://docbook.org/ns/docbook">
  &reftitle.runtime;
@@ -20,7 +20,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>
@@ -44,7 +44,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,9 +76,10 @@
      </term>
      <listitem>
       <simpara>
-       序列化后大于该字节数的值会在存储前被压缩（当前使用 LZ4）。
-       设为 <literal>-1</literal>（默认值）则完全禁用压缩。
-       压缩大值可以节省共享内存，代价是存取时多消耗一些 CPU。
+       序列化后大于该字节数的值会在存储前被压缩（自 Yac 2.4.0 起使用 LZ4）。超过
+       <literal>1M</literal> 存储条目上限（<constant>YAC_MAX_RAW_COMPRESSED_LEN</constant>）的值无论本设置如何都会被压缩，因为它们无法以未压缩形式存储。默认值 <literal>4K</literal> 表示开启压缩；
+       <literal>-1</literal> 对低于存储条目上限的值禁用压缩；其他正值会被钳制到 <literal>1024</literal>..<literal>1M</literal>
+       区间内。压缩大值可以节省共享内存，代价是存取时多消耗一些 CPU。
       </simpara>
      </listitem>
     </varlistentry>
@@ -112,9 +113,7 @@
      </term>
      <listitem>
       <simpara>
-       在 <literal>CLI</literal> SAPI 下运行时是否启用 Yac。
-       默认禁用，因为命令行脚本通常启动后立即结束，
-       创建共享内存段毫无意义。
+       在 <literal>CLI</literal> SAPI 下运行时是否启用 Yac。默认禁用，因为命令行脚本通常启动后立即结束，创建共享内存段毫无意义。
       </simpara>
      </listitem>
     </varlistentry>
@@ -125,11 +124,7 @@
      </term>
      <listitem>
       <simpara>
-       用于存放键和元信息的哈希槽位所占用的共享内存大小。
-       每个槽位是固定大小的结构，因此这个值决定了能同时跟踪多少条目。
-       默认为 <literal>4M</literal>。
-       Yac 将这块区域切分成若干段，每段大小为 4M，
-       因此该值必须是 <literal>4M</literal> 的倍数。
+       用于存放键表的共享内存大小。它限制了能同时存在的条目数量——默认的 <literal>8M</literal> 大约能容纳 65,536 个条目。如果命中率下降且 <literal>kicks</literal> 攀升，请调大该值；关于键表写满后的行为以及何时才真正构成问题，参见<xref linkend="yac.memory-management"/>。
       </simpara>
      </listitem>
     </varlistentry>
@@ -140,13 +135,10 @@
      </term>
      <listitem>
       <simpara>
-       存储前把任意 PHP 值转换成字节序列所用的序列化器。
-       可选值为 <literal>php</literal>（默认）、<literal>json</literal>、
-       <literal>igbinary</literal> 和 <literal>msgpack</literal>。
-       后三者需要扩展以相应支持编译。
+       存储前把任意 PHP 值转换成字节序列所用的序列化器。可选值为 <literal>php</literal>（默认）、<literal>json</literal>、
+       <literal>igbinary</literal> 和 <literal>msgpack</literal>。后三者需要扩展以相应支持编译。
        <literal>igbinary</literal> 和 <literal>msgpack</literal>
-       等二进制序列化器通常比 <literal>php</literal> 更快，
-       产生的数据也更小。
+       等二进制序列化器通常比 <literal>php</literal> 更快，产生的数据也更小。
       </simpara>
      </listitem>
     </varlistentry>
@@ -157,18 +149,17 @@
      </term>
      <listitem>
       <simpara>
-       用于存放实际值的共享内存大小，默认为 <literal>64M</literal>。
-       Yac 以每段 4M 的方式分配这块区域，
-       因此该值必须是 <literal>4M</literal> 的倍数。
-       当区域写满时，最久未使用的条目会被踢出，为新条目腾出空间。
+       用于存放值的共享内存大小。值在一个个 4M 的段上，由一个只进不退的分配器（bump allocator）分配；当没有任何段装得下新值时，分配器游标会绕回起点，最旧的值会被悄悄覆盖（即一次回收，
+       <literal>recycle</literal>）。此后对它们的读取会退化为未命中，由一个完整性校验机制检出。如果在槽位尚有余量时 <literal>recycles</literal> 仍在攀升，请调大该值；或者启用
+       <link linkend="ini.yac.compress-threshold">yac.compress_threshold</link>
+       来压缩大载荷。参见<xref linkend="yac.memory-management"/>。
       </simpara>
      </listitem>
     </varlistentry>
 
   </variablelist>
  </para>
 </section>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml