playbook/skills/tsl-syntax-reference/references/10_runtime_context_and_with.md

TSL 运行时上下文、服务与全局缓存

文档类型：语法主线 是否可直接用于生成代码：仅部分 是否含可直接照写示例：是 是否含不可照写反例：是 遇到不确定时：先按本页候选页继续判断；05_functions_and_calls.md、06_expressions_and_operators.md、14_ts_sql.md、15_debug_and_profiler.md、19_namespace_libpath_and_unit_runtime.md、21_builtin_runtime_objects.md；函数事实使用 tsl-api-reference skill；仍在语法层但不命中时回到本 Skill 路由中心 index.md；如果问题已经超出语法层，停止并交接给对应事实所有者

这一篇只处理运行时环境参数、块环境 with 语句、with 后缀、# 网格调用、timeout 后缀、dupvalue(...) 和全局缓存，不处理任何金融业务语义。

本篇职责

回答“setSysParam / getSysParam 怎样用、sysParams[...] 是什么、块环境 with *, values do / with **, values do 怎样写、#Func() with array(...) 这种后缀环境调用怎样写，网格调用怎样取回结果，以及全局缓存最小读写规则是什么”。

智能体运行时上下文判断流程

1. 先判断要操作系统参数、运行时上下文对象、块环境 with 语句、with 后缀调用、# 网格调用、timeout 后缀，还是全局缓存函数。
2. 系统参数优先用本页明确的 setSysParam / getSysParam / sysParams[...] 形态。
3. #Func() with array(...) 只作为运行时环境调用写法，不要套到普通本地函数。
4. 网格调用返回的不是最终值；需要最终结果时继续写 dupvalue(...)。
5. 全局缓存读写要成对出现，并明确键和值的生命周期。
6. 普通函数调用回到 05_functions_and_calls.md，不要把运行时服务写成普通语法糖；缓存值参与 select 时，查询语法仍回到 14_ts_sql.md。
7. 如果问题是内置运行时对象本身，转到 21_builtin_runtime_objects.md。
8. 本地函数后缀 with 属于反例时不要照写。
9. 没有对应代码块时不要发明运行时上下文/运行时服务/全局缓存写法。

核心规则

• TSL 有一组运行时系统参数；本页只写通用语法形态。
• setSysParam(key, value) 和 getSysParam(key) 可以直接用字符串键。
• sysParams[key] 可以直接读写这些运行时参数。
• 块环境语句可写成 with *, sys_param_values do begin ... end 或 with **, sys_param_values do begin ... end。
• with * 会把提供的系统参数合并进当前运行时上下文；不要依赖它在块结束后自动恢复外层值。
• with ** 会用提供的系统参数建立隔离块环境；块结束后恢复外层系统参数。
• 后缀 with 形式写在函数文件调用后面：#Func() with array(...)。
• with array(...) 只在该次调用里临时覆盖对应键，调用结束后会恢复外部原值。
• 如果外部原值本来不存在，with array(...) 调用结束后，对应键会恢复成 nil。
• 不要把上面的后缀 with 直接泛化成“任何本地函数调用后面都能接 with array(...)”；本地函数后缀 with 属于反例。
• 本页只收通用键的例子；像 pn_stock()、pn_date() 这类金融上下文参数，统一使用 tsl-api-reference skill 查函数事实。
• 网格调用的最小写法是 r := #Func(args);。
• 网格调用返回的不是最终值；用 dupvalue(r) 取回结果。
• timeout N 后缀可直接接在网格调用后面。
• 全局缓存函数的参数规格使用 tsl-api-reference skill 按名查询；本页只保留缓存引用的运行时行为示例。
• 写入和读取全局缓存成功时返回 1。
• 从全局缓存取出的值，ifCache(v) 会返回 1。
• 一旦对取出的缓存值做本地写入，它会立刻实例化；写入后 ifCache(v) 返回 0。
• checkGlobalCacheExpired(v) 对同名缓存的最新引用返回 0；同名缓存被重置后，旧引用会变成过期状态并返回 1。
• 全局缓存取出的值可以直接参与 select。

可直接照写示例

直接设置和读取系统参数：

代码块身份：可直接照写示例

setSysParam("a", 123);
setSysParam("b", "XYZ");
writeLn(getSysParam("a"));
writeLn(getSysParam("b"));

结果说明：

• 依次输出 123、XYZ

代码块身份：输出片段

123
XYZ

sysParams[...] 直接读写：

代码块身份：可直接照写示例

sysParams["a"] := 321;
sysParams["b"] := "QQ";
writeLn(sysParams["a"]);
writeLn(sysParams["b"]);
writeLn(getSysParam("a"));

结果说明：

• 依次输出 321、QQ、321
• 说明 sysParams[...] 和 getSysParam(...) / setSysParam(...) 指向的是同一组运行时环境参数

块环境 with *

代码块身份：可直接照写示例

setSysParam("a", 1);
param_values := array("a": 2, "b": 3);

with *, param_values do
begin
    writeLn(getSysParam("a"));
    writeLn(getSysParam("b"));
end

writeLn(getSysParam("a"));
writeLn(getSysParam("b"));

结果说明：

• 块内输出 2、3
• 块后输出 2、3
• 说明 with * 会把传入键合并进当前系统参数上下文；不要把它当成自动恢复外层值的隔离块

with *, SysParamArray do 使用当前所有系统参数：

代码块身份：可直接照写示例

setSysParam("a", 10);
setSysParam("b", 20);
with *, SysParamArray do
begin
    writeLn(getSysParam("a"));
    writeLn(getSysParam("b"));
end

代码块身份：输出片段

10
20

说明：

• SysParamArray 是特殊关键字，表示引用当前所有系统参数
• with *, SysParamArray do 把当前系统参数作为块环境传入
• 这是服务端环境的常用写法，用于保持系统参数上下文

块环境 with **

代码块身份：可直接照写示例

setSysParam("a", 1);
setSysParam("b", 9);
param_values := array("b": 4);

with **, param_values do
begin
    writeLn(getSysParam("a") = nil);
    writeLn(getSysParam("b"));
end

writeLn(getSysParam("a"));
writeLn(getSysParam("b"));

结果说明：

• 块内输出 1、4
• 块后输出 1、9
• 说明 with ** 不继承未传入的外层系统参数，并且块结束后恢复外层系统参数

沿用同一个 TestDo.tsf，看 with array(...) 的覆盖边界：

代码块身份：配置片段 / 概念骨架 代码块说明：多文件结构骨架；依赖函数文件查找路径，不是可直接复制的单文件最小示例。

// TestDo.tsf
function TestDo();
begin
    return array(getSysParam("a"), getSysParam("b"));
end;

// main.tsl
setSysParam("a", 7);
setSysParam("b", 8);
r := #TestDo() with array("a": 101, "b": 202);
writeLn(r[0]);
writeLn(r[1]);
writeLn(getSysParam("a"));
writeLn(getSysParam("b"));

结果说明：

• r[0] 输出 101
• r[1] 输出 202
• 调用结束后，外层 getSysParam("a") 输出 7
• 调用结束后，外层 getSysParam("b") 输出 8
• 说明 with array(...) 是“只在该次调用里临时覆盖，再恢复外部原值”

沿用上一个 TestDo.tsf，只把 main.tsl 改成下面这样：

代码块身份：配置片段 / 概念骨架 代码块说明：多文件结构骨架；依赖函数文件查找路径，不是可直接复制的单文件最小示例。

// main.tsl

r := #TestDo() with array("a": 101, "b": 202);
writeLn(r[0]);
writeLn(r[1]);
writeLn(getSysParam("a") = nil);
writeLn(getSysParam("b") = nil);

结果说明：

• 依次输出 101、202、1、1
• 说明外层原值不存在时，调用后不是“泄露”成 101 / 202，而是恢复成 nil

# 网格调用与 dupvalue

网格调用函数：

代码块身份：可直接照写示例

writeLn(dupvalue(#AddOne(5)));

function AddOne(v);
begin
    return v + 1;
end;

结果说明：

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

代码块身份：输出片段

6

网格调用数组表达式：

代码块身份：可直接照写示例

items := array(1, 2, 3, 4, 5);
grid_result := #(items * 2);
writeLn(tostn(dupvalue(grid_result)));

代码块身份：输出片段

array(2,4,6,8,10)

说明：

• #(表达式) 可以对表达式进行网格计算
• #(items * 2) 返回网格句柄
• dupvalue(grid_result) 取回最终结果数组
• 网格计算常用于大规模数组的分布式并行运算

网格调用的 timeout

代码块身份：可直接照写示例

writeLn(dupvalue(#AddOne(5) timeout 3000));

function AddOne(v);
begin
    return v + 1;
end;

结果说明：

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

setGlobalCache、getGlobalCache 与 ifCache

代码块身份：可直接照写示例

source_data := array(1, 2, 3);
writeLn(setGlobalCache("PB_TEST_GC_BASIC", source_data));
writeLn(getGlobalCache("PB_TEST_GC_BASIC", cached_data));
writeLn(ifCache(cached_data));
writeLn(length(cached_data));
writeLn(cached_data[0], ',', cached_data[1], ',', cached_data[2]);

结果说明：

• setGlobalCache("PB_TEST_GC_BASIC", source_data) 返回 1
• getGlobalCache("PB_TEST_GC_BASIC", cached_data) 返回 1
• 取出的 cached_data 上 ifCache(cached_data) 返回 1
• cached_data 长度是 3，内容是 1,2,3

说明：

• TSL 标识符大小写无关，setGlobalCache 和 SetGlobalCache 等价
• 推荐使用小写 setGlobalCache、getGlobalCache 以保持一致性
• setGlobalCache(key, value) 写入缓存，可选第三参数指定过期时间（秒）
• getGlobalCache(key, out_var) 读取缓存到输出变量

checkGlobalCacheExpired

代码块身份：可直接照写示例

setGlobalCache("PB_TEST_GC_EXPIRE", array(1, 2, 3));
getGlobalCache("PB_TEST_GC_EXPIRE", cache_ref);
writeLn(checkGlobalCacheExpired(cache_ref));
setGlobalCache("PB_TEST_GC_EXPIRE", array(1, 2, 3, 4));
writeLn(checkGlobalCacheExpired(cache_ref));

结果说明：

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

写入后会实例化

代码块身份：可直接照写示例

setGlobalCache("PB_TEST_GC_DETACH", array(1, 2, 3));
getGlobalCache("PB_TEST_GC_DETACH", local_copy);
writeLn(ifCache(local_copy));
local_copy[0] := 100;
writeLn(ifCache(local_copy));
writeLn(local_copy[0], ',', local_copy[1], ',', local_copy[2]);

结果说明：

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

全局缓存参与 select

代码块身份：可直接照写示例

source_table := array((1, 2), (3, 4), (2, 1));
setGlobalCache("PB_TEST_GC_SELECT", source_table);
getGlobalCache("PB_TEST_GC_SELECT", cached_table);
query_result := select * from cached_table order by [0] desc end;
writeLn(dataType(query_result));
writeLn(mrows(query_result));
writeLn(query_result[0][0], ',', query_result[0][1], ';', query_result[1][0], ',', query_result[1][1], ';', query_result[2][0], ',', query_result[2][1]);

结果说明：

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

本页不生成的范围

• 网格超时触发错误时的完整边界
• getGlobalCacheInfo、listGlobalCache、listGlobalCacheRemoved
• 初始化 TSL、监控线程、回收策略与兼容旧系统方案
• with [S => ..., T => ...] do 块语句
• {$include ...} 包含文件指令

这些名称只作为边界提示，不作为本页可生成模板。

默认生成模板

最小运行时环境入口的默认骨架如下：

代码块身份：可直接照写示例

setSysParam("a", 1);
writeLn(getSysParam("a"));

需要网格调用结果时，优先从下面这个模板起步：

代码块身份：可直接照写示例

writeLn(dupvalue(#AddOne(5)));

function AddOne(v);
begin
    return v + 1;
end;

需要缓存时，从 setGlobalCache / getGlobalCache 那一节选择模板。

禁止项

• 把系统参数页直接写成金融函数页。
• 把 #Func() with array(...) 误判成也能直接套在本地函数 Demo() 后面。
• 把 with * 误判成会自动恢复外层系统参数。
• 以为 with array(...) 改的是全局永久值，不会恢复外层原环境。
• 把网格句柄直接当最终值用，而不做 dupvalue(...)。
• 以为从全局缓存取出的值，本地写入后仍然保持缓存身份。
• 以为旧缓存引用在同名缓存被重置后还会继续视为“未过期”。
• r := #Func(args); 保存的是网格调用句柄；需要最终结果时继续写 dupvalue(r)。

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

cached_result := Demo() with array("a": 11);

function Demo();
begin
    return getSysParam("a");
end;

上面这种“本地函数后缀 with”写法不作为可写事实；常见报错是 Statement missing terminator，随后出现 function compile error。