feat(thuxyj): 为西游记增加 sync 模块

mud/thuxyj/plugins/lib/sync.tin

@@ -0,0 +1,122 @@
+#nop vim: set filetype=tt:;
+
+/*
+本文件属于 PaoTin++ 的一部分。
+PaoTin++ © 2020~2023 的所有版权均由担子炮(dzp <danzipao@gmail.com>) 享有并保留一切法律权利
+你可以在遵照 GPLv3 协议的基础之上使用、修改及重新分发本程序。
+*/
+
+///=== {
+///// sync 是一个服务器同步机制，可以确保服务器已经处理完了之前发送的命令队列。
+///// 假设服务器是按照顺序处理客户端发送的命令，那么因为存在网络延迟，因此客户端
+///// 可能已经发送了多个命令在网络上，但还没有到达服务器，或者服务器因为繁忙所以
+///// 将其放入了命令缓冲队列尚未响应。
+/////
+///// 但有些时候，客户端需要明确服务器是否已经处理了之前发送的命令。此时可以使用
+///// 本模块。其基本原理是，通过发送别致同步符号，并请求服务器回显该符号，以等待
+///// 服务器处理完之前发送的命令。如果收到了服务器的回显，则认为命令缓冲已空，并
+///// 可以进行后续操作。
+///// };
+
+#var lib_sync[META] {
+    {NAME}      {服务器同步}
+    {DESC}      {和服务器进行同步，本模块为北侠版}
+    {AUTHOR}    {担子炮}
+    {NOTE}      {}
+    {CONFIG}    {}
+};
+
+///=== {
+// #@ sync.UUID
+//    用来生成一个唯一的同步符号。
+// };
+#func {sync.UUID} {
+    #return {@uuid{}};
+};
+
+///=== {
+// ## sync.Wait <回调代码> [<同步符号>]
+//    用来和服务器进行同步，参数说明如下：
+//    1. 回调代码
+//       回调代码会在与服务器同步之后执行。
+//    2. 同步符号（可选）
+//       同步符号参数用来对本次同步进行唯一标识，只能由大小写字母、数字、连字符、
+//       下划线、小数点、斜线构成。
+//       本参数为可选值，如果省略，则无法通过 sync.Ignore 取消回调
+// };
+#alias {sync.Wait} {
+    #local callback {%1};
+    #local uuid     {%2};
+
+    #if { {$callback} == {} } {
+        xtt.Usage sync.Wait 回调代码不能为空;
+        #return;
+    };
+
+    #if { {$uuid} == {%*{[^a-zA-Z0-9_./-]}%*} } {
+        xtt.Usage sync.Wait 同步符号不能这么写;
+        #return;
+    };
+
+    #if { "$uuid" == "" } {
+        #format uuid {%U};
+    };
+
+    sync.handle {$uuid} {$callback};
+
+    xtt.Send {set public sync-$uuid};
+};
+
+///=== {
+// #@ sync.Wait <回调代码>
+//    函数版的 sync.Wait 相比别名版的 sync.Wait，省略了同步符号参数要求，
+//    改由 sync 模块自行生成，并作为返回值返回给用户。
+// };
+#func {sync.Wait} {
+    #local callback {%1};
+
+    #if { {$callback} == {} } {
+        xtt.Usage sync.Wait 回调代码不能为空;
+        #return;
+    };
+
+    #local uuid {};
+    #format uuid {%U};
+
+    sync.Wait {$callback} {$uuid};
+
+    #return {$uuid};
+};
+
+#nop 这里保存同步符号和回调代码的对应关系。;
+#var gSyncHandlers {};
+
+#alias {sync.handle} {
+    #local uuid     {%1};
+    #local callback {%2};
+    #var {gSyncHandlers[$uuid]} {$callback};
+};
+
+///=== {
+// ## sync.Ignore <同步符号>
+//    忽略指定的同步信息，将不会再触发回调代码。
+// };
+#alias {sync.Ignore} {
+    #local uuid {%1};
+    #unvar {gSyncHandlers[$uuid]};
+};
+
+#nop 根据服务器返回的信息，调用相应的回调代码。;
+#action {^设定环境变数：public = "sync-%S"$E} {
+    #local uuid {%1};
+
+    ga.Confirm {set public sync-$uuid};
+
+    #local callback {$gSyncHandlers[$uuid]};
+    #unvar {gSyncHandlers[$uuid]};
+    #if { {$callback} != {} } {
+        $callback;
+    };
+
+    #line gag;
+};