update to 2.4.3 version (build 403)

add config: swoole.max_wait_time (default 5) add constant MAIN_WORKER add getExpireTS() for LightCache fix savePersistence() bug add zm_go() to prevent errors
2026-07-23 00:25:35 +08:00 · 2021-03-29 15:34:24 +08:00
parent 202c8aee77
commit 6b872c6f74
32 changed files with 1280 additions and 882 deletions
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -20,4 +20,35 @@ ps aux | grep vendor/bin/start | grep -v grep | awk '{print $2}' | xargs kill -9
 # 然后使用下面的这条命令，假设最小的pid是23643
 kill -INT 23643
 # 如果使用 ps aux 看不到框架相关进程，证明关闭成功，否则需要使用第一条强行杀死
-```
+```
+
+## 出现 deadlock 字样
+
+一般情况下，如果误操作框架可能会报如下图的错误：
+
+```
+===================================================================
+ [FATAL ERROR]: all coroutines (count: 1) are asleep - deadlock!
+===================================================================
+
+ [Coroutine-1]
+--------------------------------------------------------------------
+#0  Swoole\Coroutine\System::sleep() called at [/Users/jerry/project/git-project/zhamao-framework/src/ZM/global_functions.php:232]
+#1  zm_sleep() called at [/Users/jerry/project/git-project/zhamao-framework/src/Module/Example/Hello.php:38]
+#2  Module\Example\Hello->onStart() called at [/Users/jerry/project/git-project/zhamao-framework/src/ZM/Event/EventDispatcher.php:205]
+#3  ZM\Event\EventDispatcher->dispatchEvent() called at [/Users/jerry/project/git-project/zhamao-framework/src/ZM/Event/EventDispatcher.php:89]
+#4  ZM\Event\EventDispatcher->dispatchEvents() called at [/Users/jerry/project/git-project/zhamao-framework/src/ZM/Event/SwooleEvent/OnWorkerStart.php:130]
+#5  ZM\Event\SwooleEvent\OnWorkerStart->onCall() called at [/Users/jerry/project/git-project/zhamao-framework/src/ZM/Framework.php:336]
+```
+
+这种错误的出现原因一般是因为协程未结束而 Worker 进程提前退出导致的，这个错误也可手动造成（在任意 Worker 进程内的位置使用 `zm_yield()` 且不使用 `zm_resume()` 恢复，期间使用 reload 或 stop 重启或停止框架就会报错）。
+
+还有一种情况是数据库、文件读取或下载上传还没有传送结束，时间已经超时，在关闭或重启框架时不得不强行切断协程的运行。这种情况建议根据下方的打印输出栈进行插错，建议将协程运行时间长的过程缩短或调长 `swoole` 配置项下面的 `max_wait_time` 时间（秒），2.4.3 版本起此参数默认为 5 秒。
+
+## 使用 LightCache 关闭时无法正常保存持久化
+
+LightCache 因为是跨内存使用的，所以每次重启和关闭框架时，都只会让其中一个进程去保存。因为在 2.4.2 版本开始，持久化的逻辑发生了更改，不再支持 `expire = -2` 进行设置持久化（因为那样会很容易让开发者写错），仅支持使用 `LightCache::addPersistence($key)` 这样的方式进行设置持久化，所以在 2.4.2 版本以后，请使用此方法进行持久化设置，保证数据不丢失。
+
+此外，2.4.2 版本起，不再支持用户手动调用 `savePersistence()` 方法，普通用户不可手动调用此方法，否则会导致数据出错。
+
+## 
--- a/docs/component/light-cache.md
+++ b/docs/component/light-cache.md
@@ -57,7 +57,9 @@ $config['light_cache'] = [

 `$value` 可存入 `bool`、`string`、`int`、`array` 等可被 `json_encode()` 的变量，闭包函数和对象不可存入。

-`$expire` 是 `int`，超时时间（秒）。如果设定了大于 0 的值，则表明是在 `$expire` 秒后自动删除。如果为 -1 则什么都不做，如果框架使用了 `stop` 或 Ctrl+C 或意外退出时数据会丢失。如果为 -2，则会将此数据持久化保存，保存在上方配置文件指定的 json 文件中，待关闭后再次启动框架会自动加载回来，不会丢失。
+`$expire` 是 `int`，超时时间（秒）。如果设定了大于 0 的值，则表明是在 `$expire` 秒后自动删除（框架中途停止不受影响）。如果为 -1 则什么都不做。框架停止后自动被清除。
+
+**注意：如果前面使用了 set() ，后面再次使用 set() 会重置 expire 过期时间为 -1（-1 是框架运行时不过期，关闭框架删除的状态），如果只需要更新值，请使用 update()。**

 ```php
 // use ZM\Store\LightCache;
@@ -88,6 +90,14 @@ public function storeAfterRemove() {
 ( 内容不存在！
 </chat-box>

+### LightCache::update()
+
+更新值而不更新状态。如果键值对不存在，则返回 false。
+
+定义：`LightCache::update(string $key, $value)`
+
+参数同 `set()`，可参考。
+
 ### LightCache::get()

 获取内容。
@@ -106,6 +116,20 @@ zm_sleep(10);
 dump(LightCache::getExpire("test")); // 返回 10
 ```

+### LightCache::getExpireTS()
+
+获取存储项要过期的时间戳。
+
+定义：`LightCache::getExpireTS(string $key)`
+
+```php
+$s = LightCache::set("test", "hello", 20); //假设这条代码执行时时间戳是 1616838482
+zm_sleep(10);
+dump(LightCache::getExpire("test")); // 返回 1616838502
+zm_sleep(10);
+dump(LightCache::getExpire("test")); // 返回 null
+```
+
 ### LightCache::getMemoryUsage()

 获取轻量缓存使用的总空间大小（字节）
@@ -157,25 +181,34 @@ dump(LightCache::getAll());
 */
 ```

-### LightCache::savePersistence()
+### LightCache::addPersistence()

-立刻保存所有被标记为持久化的缓存项到磁盘。
+添加持久化存储的键。

-!!! note "提示"
+用法：`LightCache::addPersistence($key)`。

-	在一般情况下，框架定时执行此方法来保存，在停止框架、reload 框架和 Ctrl+C 停止框架的时候，均会执行保存。
+注：只需调用一次即可，无需多次重复调用，也不需要设置 expire 为 -2 了。（2.4.2 起可用此方法）。
+
+详见下方 **持久化**。
+
+### LightCache::removePersistence()
+
+删除持久化的键。
+
+用法：`LightCache::removePersistence($key)`。
+
+注：只需调用一次即可，无需多次重复调用，也不需要设置 expire 为非 -2 了。（2.4.2 起可用此方法）。

 ### 持久化

-将 `set()` 的 expire 设置为 -2 即可。
+使用 `LightCache::addPersistence($key)` 添加对应需要持久化的键名即可。

 ```php
 /**
- * @CQCommand("store")
+ * @OnStart()
 */
-public function store() {
-    LightCache::set("msg_time", time(), -2);
-    return "OK!";
+public function onStart() {
+    LightCache::addPersistence("msg_time");
 }
 /**
 * @CQCommand("getStore")
@@ -187,11 +220,11 @@ public function getStore() {

 <chat-box>
 ^ 我在 2021-01-05 15:21:00 发送这条消息
-) store
-( OK!
+) getStore
+( 2021-01-05 15:20:00
 ^ 这时我用 Ctrl+C 停止框架，过一会儿再启动
 ) getStore
-( 存储时间：2021-01-05 15:21:00
+( 存储时间：2021-01-05 15:20:00
 </chat-box>

 ### 数据加锁
--- a/docs/guide/basic-config.md
+++ b/docs/guide/basic-config.md
@@ -43,6 +43,7 @@
 | `worker_num`            | Worker 工作进程数                                            | 运行框架的主机 CPU 核心数           |
 | `dispatch_mode`         | 数据包分发策略，见 [文档](https://wiki.swoole.com/#/server/setting?id=dispatch_mode) | 2                                   |
 | `max_coroutine`         | 最大协程并发数                                               | 300000                              |
+| `max_wait_time`         | 退出进程时等待协程恢复的最长时间（秒）                       | 5（2.4.3 版本后默认值）             |
 | `task_worker_num`       | TaskWorker 工作进程数                                        | 默认不开启（此参数被注释）          |
 | `task_enable_coroutine` | TaskWorker 工作进程启用协程                                  | 默认不开启（此参数被注释）或 `bool` |

--- a/docs/update/v2.md
+++ b/docs/update/v2.md
@@ -1,8 +1,14 @@
 # 更新日志（v2 版本）

-# v2.4.2 (build 402)
+## v2.4.3 (build 403)

-> 更新时间：202.3.27
+> 更新时间：2021.3.29
+
+- 
+
+## v2.4.2 (build 402)
+
+> 更新时间：2021.3.27

 - 更改：`WORKING_DIR` 常量的含义
 - 修复：未指定 `--remote-terminal` 参数时还依旧开启远程终端的 bug