paotin/plugins/lib/sync.tin

#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 {%21};
    #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};
    sync.send {$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};

    #line sub var sync.Wait {$callback} {$uuid};

    #return {$uuid};
};

///=== {
// ## sync.ClassWait <回调代码> [<同步符号>]
//    类似于 sync.Wait，但会在 #class 消亡时自动忽略，不需要手动 sync.Ignore，提高易用性。
// };
#alias {sync.ClassWait} {
    #local callback {%21};
    #local uuid     {%2};

    #if { {$callback} == {} } {
        xtt.Usage sync.ClassWait 回调代码不能为空;
        #return;
    };

    #if { {$uuid} == {%*{[^a-zA-Z0-9_./-]}%*} } {
        xtt.Usage sync.ClassWait 同步符号不能这么写;
        #return;
    };

    #if { "$uuid" == "" } {
        #format uuid {%U};
    };

    #info session save;
    #local class {$info[SESSION][CLASS]};
    #unvar info[SESSION];
    #if { "$class" != "" } {
        #line sub var ttevent.HandleOnce {CLASS DESTROYED $class} {event} {event} {sync.Ignore $uuid};
    };

    sync.handle {$uuid} {$callback};
    sync.send {$uuid};
};

///=== {
// #@ sync.ClassWait <回调代码>
//    函数版的 sync.ClassWait 相比别名版的 sync.ClassWait，省略了同步符号参数要求，
//    改由 sync 模块自行生成，并作为返回值返回给用户。
// };
#func {sync.ClassWait} {
    #local callback {%1};

    #if { {$callback} == {} } {
        xtt.Usage sync.ClassWait 回调代码不能为空;
        #return;
    };

    #local uuid {};
    #format uuid {%U};

    #line sub var sync.ClassWait {$callback} {$uuid};

    #return {$uuid};
};

VAR {同步符号对应的回调代码} gSyncHandlers {};

#alias {sync.handle} {
    #local uuid     {%1};
    #local callback {%2};
    #var {gSyncHandlers[$uuid]} {$callback};
};

///=== {
// ## sync.Ignore <同步符号>
//    忽略指定的同步信息，将不会再触发回调代码。
//    根据设计，大部分情况下你不需要手动 sync.Ignore，参见 sync.ClassWait。
// };
#alias {sync.Ignore} {
    #local uuid {%1};
    #unvar {gSyncHandlers[$uuid]};
};

#alias {sync.send} {
    errLog BUG: 待实现。;
    #return;
};