playbook/docs/tsl/syntax/30_runtime_services_and_global_cache.md

Runtime Services And Global Cache

文档类型：语法主线 是否可直接用于生成代码：仅部分 是否含已验证可执行示例：是 是否含已验证反例：是 遇到不确定时跳转到：16_debug_and_profiler.md、24_builtin_runtime_objects.md、12_pitfalls.md

手册位置：第 30 篇，共 32 篇。上一篇：29_ts_sql_advanced.md。下一篇：31_complex_and_weakref.md。

这一篇只讲当前解释器下已经实际跑通的运行时服务主干：# 网格调用、timeout 后缀，以及全局缓存的最小可用函数组。

这一篇解决什么问题

回答“网格调用现在怎样写，全局缓存最稳的读写方式是什么，以及什么时候缓存值会失效或脱离缓存身份”。

必须记住的规则

• 网格调用的最小写法是 r := #Func(args);。
• 网格调用返回的不是最终值；当前已验证可以用 dupvalue(r) 取回结果。
• timeout N 后缀当前已验证可直接接在网格调用后面。
• SetGlobalCache(name, value) 当前已验证返回 1 表示设置成功。
• GetGlobalCache(name, outVar) 当前已验证返回 1 表示取出成功。
• 从全局缓存取出的值，ifcache(v) 当前会返回 1。
• 一旦对取出的缓存值做本地写入，它会立刻实例化；写入后 ifcache(v) 返回 0。
• CheckGlobalCacheExpired(v) 对当前版本的缓存返回 0；同名缓存被重置后，旧引用会变成过期状态并返回 1。
• 当前已验证：全局缓存取出的值可以直接参与 select。

已验证语法

# 网格调用与 dupvalue

代码块身份：已验证可执行示例

program test;
function AddOne(v);
begin
    return v + 1;
end;
begin
    WriteLn(dupvalue(#AddOne(5)));
end.

已验证运行结果：

• #AddOne(5) 可以执行
• dupvalue(r) 返回最终结果 6

网格调用的 timeout

代码块身份：已验证可执行示例

program test;
function AddOne(v);
begin
    return v + 1;
end;
begin
    WriteLn(dupvalue(#AddOne(5) timeout 3000));
end.

已验证运行结果：

• timeout 3000 这种后缀写法可以通过并正常执行
• 上例输出 6

SetGlobalCache、GetGlobalCache 与 ifcache

代码块身份：已验证可执行示例

program test;
begin
    v1 := array(1, 2, 3);
    WriteLn(SetGlobalCache("PB_TEST_GC_BASIC", v1));
    WriteLn(GetGlobalCache("PB_TEST_GC_BASIC", v2));
    WriteLn(ifcache(v2));
    WriteLn(length(v2));
    WriteLn(v2[0], ',', v2[1], ',', v2[2]);
end.

已验证运行结果：

• SetGlobalCache("PB_TEST_GC_BASIC", v1) 返回 1
• GetGlobalCache("PB_TEST_GC_BASIC", v2) 返回 1
• 取出的 v2 上 ifcache(v2) 返回 1
• v2 长度是 3，内容是 1,2,3

CheckGlobalCacheExpired

代码块身份：已验证可执行示例

program test;
begin
    SetGlobalCache("PB_TEST_GC_EXPIRE", array(1, 2, 3));
    GetGlobalCache("PB_TEST_GC_EXPIRE", v);
    WriteLn(CheckGlobalCacheExpired(v));
    SetGlobalCache("PB_TEST_GC_EXPIRE", array(1, 2, 3, 4));
    WriteLn(CheckGlobalCacheExpired(v));
end.

已验证运行结果：

• 刚取出的缓存引用上，CheckGlobalCacheExpired(v) 返回 0
• 同名缓存被重新设置后，旧引用上的 CheckGlobalCacheExpired(v) 返回 1

写入后会实例化

代码块身份：已验证可执行示例

program test;
begin
    SetGlobalCache("PB_TEST_GC_DETACH", array(1, 2, 3));
    GetGlobalCache("PB_TEST_GC_DETACH", v);
    WriteLn(ifcache(v));
    v[0] := 100;
    WriteLn(ifcache(v));
    WriteLn(v[0], ',', v[1], ',', v[2]);
end.

已验证运行结果：

• 刚取出时 ifcache(v) 返回 1
• 对 v[0] 赋值后，ifcache(v) 立即返回 0
• 写入后的本地值内容是 100,2,3

全局缓存参与 select

代码块身份：已验证可执行示例

program test;
begin
    src := array((1, 2), (3, 4), (2, 1));
    SetGlobalCache("PB_TEST_GC_SELECT", src);
    GetGlobalCache("PB_TEST_GC_SELECT", v);
    q := select * from v order by [0] desc end;
    WriteLn(datatype(q));
    WriteLn(mrows(q));
    WriteLn(q[0][0], ',', q[0][1], ';', q[1][0], ',', q[1][1], ';', q[2][0], ',', q[2][1]);
end.

已验证运行结果：

• 对缓存值做 select 可以正常执行
• 返回结果的 datatype 是 5
• 行数是 3
• 排序后内容依次是 (3,4)、(2,1)、(1,2)

暂不在本页展开的部分

• 网格调用里的 with array(...) 系统参数传递
• 网格超时触发错误时的完整边界
• GetGlobalCacheInfo、ListGlobalCache、ListGlobalCacheRemoved
• 初始化 TSL、监控线程、回收策略与兼容旧系统方案

最小可编译示例

如果你只想先记住最短骨架，从下面这个网格调用模板起步：

代码块身份：已验证可执行示例

program test;
function AddOne(v);
begin
    return v + 1;
end;
begin
    WriteLn(dupvalue(#AddOne(5)));
end.

需要缓存时，再从 SetGlobalCache / GetGlobalCache 那一节开始。

常见误写

• 把网格句柄直接当最终值用，而不做 dupvalue(...)。
• 以为从全局缓存取出的值，本地写入后仍然保持缓存身份。
• 以为旧缓存引用在同名缓存被重置后还会继续视为“未过期”。

代码块身份：反例 / 不可照写

r := #AddOne(5);
WriteLn(r);

上面这种写法不要直接当成“已经拿到计算结果”。当前已验证的稳定取值方式是 dupvalue(r)。

跳转指引

• 回看调试与 profiler：见 16_debug_and_profiler.md
• 回看运行时环境参数：见 11_runtime_context_and_with.md
• 回看语法主入口：见 index.md