From 59999583447ad12960c64f90e5172b4d2cb8f0a2 Mon Sep 17 00:00:00 2001 From: Xinchen Hui Date: Wed, 26 Aug 2026 18:52:19 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20Yac=20=E6=89=A9=E5=B1=95?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E7=9A=84=E4=B8=AD=E6=96=87=E7=BF=BB=E8=AF=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- reference/yac/book.xml | 80 +++++++++ reference/yac/constants.xml | 129 +++++++++++++++ reference/yac/ini.xml | 191 ++++++++++++++++++++++ reference/yac/setup.xml | 133 +++++++++++++++ reference/yac/yac.xml | 112 +++++++++++++ reference/yac/yac/add.xml | 144 ++++++++++++++++ reference/yac/yac/construct.xml | 97 +++++++++++ reference/yac/yac/delete.xml | 138 ++++++++++++++++ reference/yac/yac/dump.xml | 281 ++++++++++++++++++++++++++++++++ reference/yac/yac/flush.xml | 92 +++++++++++ reference/yac/yac/get.xml | 131 +++++++++++++++ reference/yac/yac/getter.xml | 100 ++++++++++++ reference/yac/yac/info.xml | 187 +++++++++++++++++++++ reference/yac/yac/set.xml | 128 +++++++++++++++ reference/yac/yac/setter.xml | 102 ++++++++++++ 15 files changed, 2045 insertions(+) create mode 100644 reference/yac/book.xml create mode 100644 reference/yac/constants.xml create mode 100644 reference/yac/ini.xml create mode 100644 reference/yac/setup.xml create mode 100644 reference/yac/yac.xml create mode 100644 reference/yac/yac/add.xml create mode 100644 reference/yac/yac/construct.xml create mode 100644 reference/yac/yac/delete.xml create mode 100644 reference/yac/yac/dump.xml create mode 100644 reference/yac/yac/flush.xml create mode 100644 reference/yac/yac/get.xml create mode 100644 reference/yac/yac/getter.xml create mode 100644 reference/yac/yac/info.xml create mode 100644 reference/yac/yac/set.xml create mode 100644 reference/yac/yac/setter.xml diff --git a/reference/yac/book.xml b/reference/yac/book.xml new file mode 100644 index 000000000..4ab1f9498 --- /dev/null +++ b/reference/yac/book.xml @@ -0,0 +1,80 @@ + + + + + + + Yac + Yac + + + &reftitle.intro; + + Yac（Yet Another Cache）是一个无锁（lock-free）的共享内存用户数据缓存， + 可以用来替代 APC 或本地 memcached。 + + + Yac 将数据存储在共享内存中，同一台机器上的每个 PHP 工作进程 + 都能直接访问，无需任何进程间通信。 + Yac 不加锁，而是依靠原子的槽位更新加上少量的冲突探测， + 因此缓存未命中（cache miss）绝不会阻塞请求； + 并发写入最坏的情况也只是某次存储失败或某次读取落空， + 调用方直接重试即可。 + + + 访问路径上没有锁，也没有进程间通信，一次读取本质上就是 + 在共享内存中做一次哈希查找。因此，Yac 极其快， + 读取延迟在微秒级；只要写入分散在不同的键上， + 吞吐量还能随着访问缓存的 worker 数量增长。 + + + 由于 Yac 用正确性保证换取速度和吞吐量， + 它最适合缓存那些生成代价高但可以轻易重建的数据： + 页面片段、配置快照、小型服务响应等本地缓存。 + 不要把它用作不可替代数据的权威存储。 + + + 从 yac 2.4.0 开始，小标量值——NULL、 + 布尔值、整数、最长 7 字节的短字符串和空数组—— + 直接存储在哈希槽（hash slot）里，而不是单独的值块 + （即“嵌入值”，embedded values）。这样每次访问都省去了 + 值内存的分配和块拷贝，显著提升性能的同时减少了内存占用。 + 2.4.0 还把压缩后端从 FastLZ 换成了 LZ4， + 使压缩数据的读取快了好几倍。 + + + + 共享内存仅在同一台机器内可见。 + 如果需要在多台服务器之间共享缓存， + 请使用 Memcached 或 Redis 等网络缓存。 + + + + + &reference.yac.setup; + &reference.yac.constants; + + &reference.yac.yac; + + + + diff --git a/reference/yac/constants.xml b/reference/yac/constants.xml new file mode 100644 index 000000000..d539b6646 --- /dev/null +++ b/reference/yac/constants.xml @@ -0,0 +1,129 @@ + + + + + + &reftitle.constants; + &extension.constants; + + + + + YAC_VERSION + (string) + + + + + + + + + YAC_MAX_KEY_LEN + (int) + + + + 键允许的最大长度，为 48 字节。 + + + + + + YAC_MAX_VALUE_RAW_LEN + (int) + + + + + + + + + YAC_MAX_RAW_COMPRESSED_LEN + (int) + + + + + + + + + YAC_SERIALIZER_PHP + (int) + + + + 使用 PHP serialize 作为序列化器。 + + + + + + YAC_SERIALIZER_JSON + (int) + + + + 使用 JSON 作为序列化器（需要 --enable-json）。 + + + + + + YAC_SERIALIZER_IGBINARY + (int) + + + + 使用 igbinary 作为序列化器（需要 --enable-igbinary）。 + + + + + + YAC_SERIALIZER_MSGPACK + (int) + + + + 使用 msgpack 作为序列化器（需要 --enable-msgpack）。 + + + + + + YAC_SERIALIZER + (string) + + + + Yac 当前使用的序列化器。 + + + + + + + + diff --git a/reference/yac/ini.xml b/reference/yac/ini.xml new file mode 100644 index 000000000..48176d655 --- /dev/null +++ b/reference/yac/ini.xml @@ -0,0 +1,191 @@ + + + + +
+ &reftitle.runtime; + &extension.runtime; + + + Yac &ConfigureOptions; + + + + &Name; + &Default; + &Changeable; + &Changelog; + + + + + yac.compress_threshold + -1 + INI_SYSTEM + + + + yac.debug + 0 + INI_ALL + + + + yac.enable + 1 + INI_SYSTEM + + + + yac.enable_cli + 0 + INI_SYSTEM + + + + yac.keys_memory_size + 4M + INI_SYSTEM + + + + yac.serializer + php + INI_SYSTEM + + + + yac.values_memory_size + 64M + INI_SYSTEM + + + + +
+ + + &ini.descriptions.title; + + + + + + yac.compress_threshold + int + + + + 序列化后大于该字节数的值会在存储前被压缩（当前使用 LZ4）。 + 设为 -1（默认值）则完全禁用压缩。 + 压缩大值可以节省共享内存，代价是存取时多消耗一些 CPU。 + + + + + + yac.debug + int + + + + 保留给调试用。截至 Yac 2.4.0，该配置项已注册但没有任何效果。 + + + + + + yac.enable + int + + + + 是否启用 Yac。如果被禁用，创建 + Yac 实例会抛出异常。 + + + + + + yac.enable_cli + int + + + + 在 CLI SAPI 下运行时是否启用 Yac。 + 默认禁用，因为命令行脚本通常启动后立即结束， + 创建共享内存段毫无意义。 + + + + + + yac.keys_memory_size + string + + + + 用于存放键和元信息的哈希槽位所占用的共享内存大小。 + 每个槽位是固定大小的结构，因此这个值决定了能同时跟踪多少条目。 + 默认为 4M。 + Yac 将这块区域切分成若干段，每段大小为 4M， + 因此该值必须是 4M 的倍数。 + + + + + + yac.serializer + string + + + + 存储前把任意 PHP 值转换成字节序列所用的序列化器。 + 可选值为 php（默认）、json、 + igbinary 和 msgpack。 + 后三者需要扩展以相应支持编译。 + igbinary 和 msgpack + 等二进制序列化器通常比 php 更快， + 产生的数据也更小。 + + + + + + yac.values_memory_size + string + + + + 用于存放实际值的共享内存大小，默认为 64M。 + Yac 以每段 4M 的方式分配这块区域， + 因此该值必须是 4M 的倍数。 + 当区域写满时，最久未使用的条目会被踢出，为新条目腾出空间。 + + + + + + +
+ + diff --git a/reference/yac/setup.xml b/reference/yac/setup.xml new file mode 100644 index 000000000..0d182afd2 --- /dev/null +++ b/reference/yac/setup.xml @@ -0,0 +1,133 @@ + + + + + + &reftitle.setup; + +
+ &reftitle.required; + + 无需外部库。 + +
+ + +
+ &reftitle.install; + + Yac 有三种安装方式：通过 PECL、通过 PIE，或从源码构建。 + + + &pecl.moved; + + + &pecl.info; + &url.pecl.package;yac。 + + + &pecl.windows.download.avail; + + + 用 PECL 安装 Yac + + + + + + 从 Yac 2.3.2 开始，可以用 &link.pie;（PHP Installer for + Extensions，PHP 扩展安装器）安装本扩展，在命令行执行： + + + 用 PIE 安装 Yac + + + + + + 安装时可以同时启用可选的序列化器： + + + 用 PIE 安装 Yac 并启用序列化器 + + + + + + 源代码托管在 + GitHub 上。 + 从源码构建扩展，在命令行执行以下命令， + 并把路径替换为本地 PHP 安装的实际路径： + + + 从源码构建 Yac + + + + + + 可用的 configure 选项如下： + + + 值在存储前会用 LZ4 压缩。LZ4 压缩后端从 Yac 2.4.0 开始使用， + 取代了此前的 FastLZ。默认情况下，Yac 使用随扩展一起打包的 + LZ4 副本，无需额外的编译选项。如果要改为链接系统的 LZ4 库， + 请使用 选项， + 这要求系统已安装 lz4.h 头文件和 + liblz4。 + + + 可以通过 、 + 或 + + 编译进备选的序列化器，相应的扩展会被注册为可选依赖。 + 运行时使用哪个序列化器由 + yac.serializer + ini 配置项选择。 + +
+ + + + &reference.yac.ini; + + +
+ &reftitle.resources; + + 此扩展没有定义任何资源类型。 + +
+ + + + diff --git a/reference/yac/yac.xml b/reference/yac/yac.xml new file mode 100644 index 000000000..683bbe1ad --- /dev/null +++ b/reference/yac/yac.xml @@ -0,0 +1,112 @@ + + + + + + + Yac 类 + Yac + + + + +
+ &reftitle.intro; + + Yac 类是访问缓存的接口。 + 同一台主机上的每个实例都是同一个共享缓存的轻量级句柄： + 所有实例读写同一份数据，创建一个实例除了句柄本身之外 + 没有任何额外分配。 + + + 传给 Yac::__construct 的可选前缀 + 会被拼接到每个键的前面，这样多个实例（或多个应用） + 可以共用同一个缓存而键互不冲突。除了常规的缓存操作 + （Yac::add、 + Yac::set、 + Yac::get、 + Yac::delete 和 + Yac::flush）之外，该类还提供 + Yac::info 和 + Yac::dump 用于检视缓存， + 并且重载了属性访问——读写对象属性就是读写一个缓存条目。 + +
+ + +
+ &reftitle.classsynopsis; + + + + Yac + + + + + Yac + + + + &Properties; + + protected + _prefix + + + + &Methods; + + + + + +
+ + + +
+ &reftitle.properties; + + + _prefix + + + 通过 Yac::__construct 设置的键前缀。 + 它会拼接到该实例使用的每个键的前面；拼接时不会自动插入 + 分隔符，需要的话请自己包含在前缀里。前缀长度不能超过 + YAC_MAX_KEY_LEN（48）字节。 + + + + +
+ + + + + + &reference.yac.entities.yac; + + + + diff --git a/reference/yac/yac/add.xml b/reference/yac/yac/add.xml new file mode 100644 index 000000000..cae4197e5 --- /dev/null +++ b/reference/yac/yac/add.xml @@ -0,0 +1,144 @@ + + + + + + + Yac::add + 存储一个值，但不覆盖已有条目 + + + + &reftitle.description; + + public boolYac::add + stringarraykeys + mixedvalue + intttl0 + + + public boolYac::add + arrayvalues + intttl0 + + + 向缓存中存储一个值。与 Yac::set 不同， + 它不会覆盖仍然有效的已有条目；遇到这种情况时存储会被拒绝。 + + + + + &reftitle.parameters; + + + keys + + + string 类型的键，或者一个由 + key => value 键值对组成的 + array，一次调用存储多个条目。 + + + + + value + + + 要存储的值。除 resource 外的所有 PHP 类型都可以存储。 + 仅在单键形式下使用；当 keys 是数组时， + 该参数位置实际上是可选的 ttl。 + + + + + ttl + + + 生存时间，单位为秒。0 表示条目永不因时间过期。 + + + + + + + + &reftitle.returnvalues; + + 成功时返回 &true;，失败时返回 &false;。 + 当键已存在且未过期时，存储同样会被拒绝（返回 &false;）。 + + + + Yac 存储条目时不加锁。在高并发竞争下，存储可能会瞬时失败； + 如果该值必须最终写入成功，请重试： + +add("key", "value")) { + // 瞬时失败时重试 +} +?> +]]> + + + + + + + &reftitle.examples; + + <methodname>Yac::add</methodname> 示例 + +add("foo", "bar")); // bool(true) +var_dump($yac->add("foo", "baz")); // bool(false)："foo" 已存在 + +// ttl 以秒为单位；0（默认值）表示条目永不过期 +$yac->add("short-lived", "value", 5); +sleep(6); +var_dump($yac->get("short-lived")); // bool(false)：已过期 + +// 一次调用存储多个键值对，并指定 ttl +$yac->add(array("a" => 1, "b" => 2), 60); +?> +]]> + + + + + + &reftitle.seealso; + + + Yac::set + Yac::get + Yac::delete + + + + + + + diff --git a/reference/yac/yac/construct.xml b/reference/yac/yac/construct.xml new file mode 100644 index 000000000..707ec2853 --- /dev/null +++ b/reference/yac/yac/construct.xml @@ -0,0 +1,97 @@ + + + + + + + Yac::__construct + 构造函数 + + + + &reftitle.description; + + public Yac::__construct + stringprefix"" + + + 创建一个新的 Yac 实例。 + 可选的 prefix 会被添加到该实例存储的每个键前面， + 这样同一台机器上的多个应用或缓存就可以使用重叠的键名而互不冲突。 + + + + + &reftitle.parameters; + + + prefix + + + 键前缀，最长 48 字节（YAC_MAX_KEY_LEN）。 + + + + + + + + &reftitle.errors; + + 当缓存被禁用（yac.enable=0） + 或 prefix 超过 48 字节时， + 会抛出 Exception。 + + + + + &reftitle.examples; + + <methodname>Yac::__construct</methodname> 示例 + +set("foo", "bar"); + +$other = new Yac("app2_"); +var_dump($other->get("foo")); // bool(false)：不同的命名空间 +$other->set("foo", "baz"); // 实际存储的键是 "app2_foo" +?> +]]> + + + + + + &reftitle.seealso; + + + Yac::set + Yac::get + + + + + + + diff --git a/reference/yac/yac/delete.xml b/reference/yac/yac/delete.xml new file mode 100644 index 000000000..32b4a3334 --- /dev/null +++ b/reference/yac/yac/delete.xml @@ -0,0 +1,138 @@ + + + + + + + Yac::delete + 从缓存中删除条目 + + + + &reftitle.description; + + public boolYac::delete + stringarraykeys + intdelay0 + + + 从缓存中删除一个或多个条目。 + + + + 注意，Yac 并不会真正把条目从缓存中移除：删除只是把条目标记为 + 过期——delay 为 0 时立即过期—— + 只有当后续的写入恰好复用了这个哈希槽时，该条目才会被覆盖： + 要么是同一个键被重新写入，要么是另一个键的插入恰好落在了这个槽上。 + 在那之前，槽位一直被占用，所以 Yac::info + 报告的 slots_used 计数不会减少， + Yac::dump 也仍会列出这些已删除的条目； + 检视 dump 输出时，需要自己检查 ttl 值把它们过滤掉。 + + + + + + &reftitle.parameters; + + + keys + + + string 类型的键，或者由待删除的键组成的 + array。 + + + + + delay + + + 条目变为失效前等待的秒数。省略或为 0 + 时，条目立即失效。正数值表示条目在这段时间内仍可读， + 到期后才失效。 + + + + + + + + &reftitle.returnvalues; + + 成功时返回 &true;；键不在缓存中时返回 &false;。 + 由于删除只是把条目标记为过期，一个已删除但尚未被覆盖的键 + 仍然算作存在：再次删除同一个键会返回 &true;。 + + + 传入键的 array 时，只有当每个键都存在才返回 + &true;；只要有任何一个键缺失，就返回 &false;。 + + + + + &reftitle.examples; + + <methodname>Yac::delete</methodname> 示例 + +set("foo", "bar"); + +var_dump($yac->delete("foo")); // bool(true)：标记为过期 +var_dump($yac->get("foo")); // bool(false)：从此读取都是未命中 +var_dump($yac->delete("foo")); // bool(true)：槽位还没被覆盖，所以又成功 +var_dump($yac->delete("never")); // bool(false)：从未存储过 + +// 删除不会释放槽位：slots_used 不减少， +// 已过期的条目仍然出现在 dump 里 +var_dump($yac->info()["slots_used"]); // int(1) +print_r($yac->dump()); // "foo" 仍在列表中；其 ttl 已过期 + +// 延迟删除：让条目再保持可读 60 秒 +$yac->set("tmp", "value"); +var_dump($yac->delete("tmp", 60)); // bool(true) + +// 一次删除多个键时，只有当每个键都存在才返回 true +var_dump($yac->delete(array("tmp", "nope"))); // bool(false)："nope" 不存在 +?> +]]> + + + + + + &reftitle.seealso; + + + Yac::set + Yac::flush + Yac::info + Yac::dump + + + + + + + diff --git a/reference/yac/yac/dump.xml b/reference/yac/yac/dump.xml new file mode 100644 index 000000000..56423f0f9 --- /dev/null +++ b/reference/yac/yac/dump.xml @@ -0,0 +1,281 @@ + + + + + + + Yac::dump + 导出缓存条目以便检查 + + + + &reftitle.description; + + public arrayYac::dump + intlimit100 + intoffset0 + + + 导出当前缓存储存的条目的元数据。值本身不会被返回。 + + + + + &reftitle.parameters; + + + limit + + + 返回条目的最大数量。 + + + limit 传 -1 会导出缓存当前持有的全部条目。 + 注意，对大型缓存构建完整列表可能占用可观的内存； + 内存紧张时，请改用 limit 和 offset 分页遍历。 + + + + + offset + + + 收集前跳过的条目数。该参数自 PECL yac 2.4.0 起可用； + 更早的版本总是从第一个条目开始。结合 limit， + 可用于对储存条目超过单次调用返回上限的缓存进行分页遍历。 + + + + + + + + &reftitle.returnvalues; + + 返回一个 array，每个导出的条目对应一个元素。 + 每个元素本身也是描述该条目的数组： + + + + index + + 条目在哈希表中的槽位索引。 + + + + hash + + 键的 64 位哈希值，用于槽位探测。 + + + + crc + + 存储值的 CRC32 校验和，用于检测撕裂读取（torn read）。 + 内嵌（embedded）条目没有值块，该字段为 0。 + + + + ttl + + 过期时间戳（Unix 时间）。0 + 表示条目永不因时间过期。注意 Yac::delete + 只是把条目标记为过期，因此已删除的条目仍可能出现在导出结果中； + ttl 非零且在过去，表明条目已过期或已被删除。 + + + + k_len + + 键的长度，单位为字节。 + + + + v_len + + 值的长度，单位为字节。对于被压缩的条目， + 这是压缩前原始值的长度 + （自 yac 2.4.0 起；更早的版本报告的是存储的压缩后长度）。 + + + + c_len + + 仅被压缩的条目有此字段（自 yac 2.4.0 起）： + 实际存入共享内存的压缩数据长度，单位为字节。 + 对比 c_len 和 v_len + 可以看出每个条目通过压缩节省了多少空间。 + + + + size + + 值块在共享内存中分配的大小，单位为字节。 + 内嵌条目为 0。 + + + + atime + + 最后访问时间（Unix 时间），每次成功的 + Yac::get 都会更新它。 + 缓存写满时，候选槽位中 atime + 最旧的条目会最先被驱逐（自 yac 2.4.0 起）。 + + + + hits + + 每个条目的命中计数器，每次成功的 + Yac::get 都会使其递增； + 条目被覆盖、删除或过期时重置（自 yac 2.4.0 起）。 + + + + embedded + + 值是否直接存储在槽位内部，而不是单独的值块中 + （自 yac 2.4.0 起）。小值——NULL、 + 布尔值、小整数、不超过 7 字节的字符串和空数组—— + 以内嵌方式存储，完全不占用值内存； + 这类条目的 crc 和 size + 均报告为 0。 + + + + key + + 缓存键，不包含实例前缀。 + + + + + + + &reftitle.examples; + + <methodname>Yac::dump</methodname> 示例 + +set("foo", "bar"); +$yac->set("baz", "qux"); + +print_r($yac->dump()); +?> +]]> + + &example.outputs.similar; + + 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 + ) + +) +]]> + + + 条目按槽位顺序列出，而不是按存储顺序。 + 内嵌条目（直接保存在槽位内部的小标量）的 + crc 和 size 为零； + 存储在独立值块中的条目带有校验和与块大小， + 被压缩的条目还额外带有 c_len。 + + + + 分页遍历大型缓存 + + limit 限制单次调用返回的条目数， + offset 表示收集前跳过的条目数， + 两者组合即可对储存条目超过单次调用返回上限的缓存进行分页遍历。 + + +dump($page_size, $page_size * ($page_num - 1)); + +var_dump(count($page)); +?> +]]> + + &example.outputs.similar; + + + + + 当缓存中的条目数少于请求页覆盖的范围时， + 返回的条目数会少于请求数； + 当 offset 指向最后一个已占用槽位之后时，返回空数组。 + + + + + + &reftitle.seealso; + + + Yac::info + + + + + + + diff --git a/reference/yac/yac/flush.xml b/reference/yac/yac/flush.xml new file mode 100644 index 000000000..f8b6d2ce9 --- /dev/null +++ b/reference/yac/yac/flush.xml @@ -0,0 +1,92 @@ + + + + + + + Yac::flush + 清空缓存 + + + + &reftitle.description; + + public boolYac::flush + + + + 删除所有缓存的值。由于缓存由同一台机器上的所有进程共享， + 这会全局清空缓存；传给 Yac::__construct + 的键前缀不会限制清空的范围。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + 返回 &true;。 + + + + + &reftitle.examples; + + <methodname>Yac::flush</methodname> 示例 + +set("foo", "bar"); + +$other = new Yac("app2_"); +$other->set("baz", "qux"); + +// flush 会清空整个缓存：所有实例的条目， +// 无论存储时使用了什么前缀 +$yac->flush(); + +var_dump($yac->get("foo")); // bool(false) +var_dump($other->get("baz")); // bool(false) +?> +]]> + + + + + + &reftitle.seealso; + + + Yac::delete + Yac::info + + + + + + + diff --git a/reference/yac/yac/get.xml b/reference/yac/yac/get.xml new file mode 100644 index 000000000..bf36d1091 --- /dev/null +++ b/reference/yac/yac/get.xml @@ -0,0 +1,131 @@ + + + + + + + Yac::get + 从缓存中取值 + + + + &reftitle.description; + + public mixedYac::get + stringarraykeys + mixeddefault&null; + + + 从缓存中取值。 + + + + + &reftitle.parameters; + + + keys + + + string 类型的键，或者由键组成的 array。 + + + + + default + + + 当请求的键（或多个键）不在缓存中时返回的值， + 自 yac 2.4.0 起可用。省略时，未命中返回 &false;。 + + + + 在 yac 2.4.0 之前，该参数位置是一个引用形式的 + $cas 令牌，而不是默认值。 + 传递过或依赖该令牌的代码在升级到 2.4.0 时必须更新。 + + + + + + + + + &reftitle.returnvalues; + + 对于 string 类型的键，命中时返回缓存的值， + 否则返回 default（未指定默认值时返回 &false;）。 + + + 对于由键组成的 array，返回一个数组， + 其中包含所有命中的值，以各自的键为索引。 + 自 yac 2.4.0 起，不在缓存中的键会被直接忽略 + （若指定了 default，则用默认值填充）； + 在 2.4.0 之前，每个缺失的键都会插入一个 &false; 占位值。 + + + + + + &reftitle.examples; + + <methodname>Yac::get</methodname> 示例 + +set("foo", "bar"); +var_dump($yac->get("foo")); // string(3) "bar" +var_dump($yac->get("missing")); // bool(false)：未命中 + +// 没有默认值时，未命中和存了 false 无法区分； +// 哨兵默认值（自 yac 2.4.0 起可用）可以区分二者 +$yac->set("flag", false); +var_dump($yac->get("flag")); // bool(false)：存的就是这个值 +var_dump($yac->get("missing", false)); // bool(false)：未命中，形态相同 +var_dump($yac->get("flag", "__NONE__")); // bool(false)：存的就是这个值 +var_dump($yac->get("missing", "__NONE__")); // string(8) "__NONE__"：未命中 + +// 传入键数组时，结果中只包含命中的键 +$yac->set("foo2", "bar2"); +var_dump($yac->get(array("foo", "foo2", "missing"))); +// array(2) { ["foo"]=> string(3) "bar" ["foo2"]=> string(4) "bar2" } +?> +]]> + + + + + + &reftitle.seealso; + + + Yac::set + Yac::__get + + + + + + + diff --git a/reference/yac/yac/getter.xml b/reference/yac/yac/getter.xml new file mode 100644 index 000000000..d3efad8f8 --- /dev/null +++ b/reference/yac/yac/getter.xml @@ -0,0 +1,100 @@ + + + + + + + Yac::__get + 以属性语法取值 + + + + &reftitle.description; + + public mixedYac::__get + stringkey + + + 从缓存中取值，读取 Yac 实例的属性时被调用： + $yac->foo 等价于 + $yac->get("foo")。 + + + + + &reftitle.parameters; + + + key + + + 属性名，被用作缓存键。 + + + + + + + + &reftitle.returnvalues; + + 命中时返回缓存的值；键不在缓存中时返回 &null;。 + + + + 与 Yac::get 不同， + 属性语法无法区分存储的 &null; 和键不存在，并且只支持单键操作。 + + + + + + &reftitle.examples; + + <methodname>Yac::__get</methodname> 示例 + +set("foo", "bar"); + +var_dump($yac->foo); // string(3) "bar" +var_dump($yac->missing); // NULL +?> +]]> + + + + + + &reftitle.seealso; + + + Yac::get + Yac::__set + + + + + + + diff --git a/reference/yac/yac/info.xml b/reference/yac/yac/info.xml new file mode 100644 index 000000000..695cbabb6 --- /dev/null +++ b/reference/yac/yac/info.xml @@ -0,0 +1,187 @@ + + + + + + + Yac::info + 获取缓存状态 + + + + &reftitle.description; + + public arrayYac::info + + + + 获取缓存系统的状态。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + 返回一个包含以下键的 array： + + + + memory_size + + 已使用的共享内存总量，单位为字节：槽位表加上值块。 + + + + slots_memory_size + + 为哈希槽位表预留的内存，单位为字节。 + + + + values_memory_size + + 为存储的值预留的内存，单位为字节。 + + + + segment_size + + 单个值内存段的大小，单位为字节。 + + + + segment_num + + 值内存段的数量。 + + + + miss + + 缓存未命中次数：查找时没有找到条目或条目已过期。 + + + + hits + + 缓存命中次数：成功找到条目的查找次数。 + + + + fails + + 存储失败次数：因无法分配值块而失败的存储次数。 + + + + kicks + + 驱逐次数：因候选槽位探测路径已满而不得不驱逐已有条目的次数。 + + + + recycles + + 分配器到达段末尾后回绕到段开头的次数。 + + + + start_time + + 共享内存缓存初始化时的 Unix 时间戳。 + + + + slots_size + + 哈希槽位的总数。 + + + + slots_used + + 当前已被占用的哈希槽位数。 + + + + + + + &reftitle.examples; + + <methodname>Yac::info</methodname> 示例 + +set("foo", "bar"); + +print_r($yac->info()); +?> +]]> + + &example.outputs.similar; + + 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 +) +]]> + + + 命中率可以按 hits / (hits + miss) 计算； + 持续增长的 kicks 或 fails + 计数器表明缓存正处于内存压力之下。 + + + + + + &reftitle.seealso; + + + Yac::dump + + + + + + + diff --git a/reference/yac/yac/set.xml b/reference/yac/yac/set.xml new file mode 100644 index 000000000..a2e92be9c --- /dev/null +++ b/reference/yac/yac/set.xml @@ -0,0 +1,128 @@ + + + + + + + Yac::set + 向缓存中存储一个值 + + + + &reftitle.description; + + public boolYac::set + stringarraykeys + mixedvalue + intttl0 + + + public boolYac::set + arrayvalues + intttl0 + + + 向缓存中存储一个值。如果键已存在， + 则覆盖已有条目，无论其是否已过期。 + + + + + &reftitle.parameters; + + + keys + + + string 类型的键，或者一个由 + key => value 键值对组成的 + array，一次调用存储多个条目。 + + + + + value + + + 要存储的值。除 resource 外的所有 PHP 类型都可以存储。 + 仅在单键形式下使用；当 keys 是数组时， + 该参数位置实际上是可选的 ttl。 + + + + + ttl + + + 生存时间，单位为秒。0 表示条目永不因时间过期。 + + + + + + + + &reftitle.returnvalues; + + 成功时返回 &true;，失败时返回 &false;。 + + + + + &reftitle.examples; + + <methodname>Yac::set</methodname> 示例 + +set("foo", "bar"); // 存储单个值 +$yac->set("foo", "baz"); // 覆盖已有条目 + +// ttl 以秒为单位：该条目 5 秒后过期 +$yac->set("short-lived", "value", 5); +sleep(6); +var_dump($yac->get("short-lived")); // bool(false)：已过期 + +// 一次调用存储多个键值对 +$yac->set(array("a" => 1, "b" => 2)); +?> +]]> + + + + + + &reftitle.seealso; + + + Yac::add + Yac::get + Yac::__set + + + + + + + diff --git a/reference/yac/yac/setter.xml b/reference/yac/yac/setter.xml new file mode 100644 index 000000000..247b6bfa2 --- /dev/null +++ b/reference/yac/yac/setter.xml @@ -0,0 +1,102 @@ + + + + + + + Yac::__set + 以属性语法存储一个值 + + + + &reftitle.description; + + public mixedYac::__set + stringkey + mixedvalue + + + 向缓存中存储一个值，写入 Yac 实例的属性时被调用： + $yac->foo = "bar" 等价于 + $yac->set("foo", "bar")，且不带 ttl。 + + + + + &reftitle.parameters; + + + key + + + 属性名，被用作缓存键。 + + + + + value + + + 要存储的值。除 resource 外的所有 PHP 类型都可以存储。 + + + + + + + + &reftitle.returnvalues; + + 返回存储的值。 + + + + + &reftitle.examples; + + <methodname>Yac::__set</methodname> 示例 + +foo = "bar"; // 存储时不带 ttl +var_dump($yac->get("foo")); // string(3) "bar" +?> +]]> + + + + + + &reftitle.seealso; + + + Yac::set + Yac::__get + + + + + + +