📝 docs(tsl): restructure agent-facing reference
Rework TSL syntax, catalog, modules, and routing docs around deterministic agent lookup and generation. Split large catalog pages into focused function fact pages, remove obsolete pending/verified/unavailable paths, and update consistency tests for the new structure.
This commit is contained in:
@@ -0,0 +1,312 @@
|
||||
# TSL 运行时上下文、服务与全局缓存
|
||||
|
||||
文档类型：语法主线
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[14_ts_sql.md](14_ts_sql.md)、[15_debug_and_profiler.md](15_debug_and_profiler.md)、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)、[../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
|
||||
这一篇只处理运行时环境参数、`with` 后缀、`#` 网格调用、`timeout` 后缀、`dupvalue(...)` 和全局缓存，不处理任何金融业务语义。
|
||||
|
||||
## 本篇职责
|
||||
|
||||
回答“`setSysParam` / `getSysParam` 怎样用、`sysParams[...]` 是什么、`#Func() with array(...)` 这种后缀环境调用怎样写，网格调用怎样取回结果，以及全局缓存最小读写规则是什么”。
|
||||
|
||||
## 智能体运行时上下文判断流程
|
||||
|
||||
1. 先判断要操作系统参数、运行时上下文对象、`with` 后缀调用、`#` 网格调用、`timeout` 后缀，还是全局缓存函数。
|
||||
2. 系统参数优先用本页明确的 `setSysParam` / `getSysParam` / `sysParams[...]` 形态。
|
||||
3. `#Func() with array(...)` 只作为运行时环境调用写法，不要套到普通本地函数。
|
||||
4. 网格调用返回的不是最终值；需要最终结果时继续写 `dupvalue(...)`。
|
||||
5. 全局缓存读写要成对出现，并明确键和值的生命周期。
|
||||
6. 普通函数调用回到 [05_functions_and_calls.md](05_functions_and_calls.md)，不要把运行时服务写成普通语法糖；缓存值参与 `select` 时，查询语法仍回到 [14_ts_sql.md](14_ts_sql.md)。
|
||||
7. 如果问题是内置运行时对象本身，转到 [21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)。
|
||||
8. 本地函数后缀 `with` 属于反例时不要照写。
|
||||
9. 没有对应代码块时不要发明运行时上下文/运行时服务/全局缓存写法。
|
||||
|
||||
## 核心规则
|
||||
|
||||
- TSL 有一组运行时系统参数；本页只写通用语法形态。
|
||||
- `setSysParam(key, value)` 和 `getSysParam(key)` 可以直接用字符串键。
|
||||
- `sysParams[key]` 可以直接读写这些运行时参数。
|
||||
- 本页明确的 `with` 形式，是写在函数文件调用后面：`#Func() with array(...)`。
|
||||
- `with array(...)` 只在该次调用里临时覆盖对应键，调用结束后会恢复外部原值。
|
||||
- 如果外部原值本来不存在，`with array(...)` 调用结束后，对应键会恢复成 `nil`。
|
||||
- 不要把上面的后缀 `with` 直接泛化成“任何本地函数调用后面都能接 `with array(...)`”；本地函数后缀 `with` 属于反例。
|
||||
- 本页只收通用键的例子；像 `pn_stock()`、`pn_date()` 这类金融上下文参数，统一到 [../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md) 查函数事实。
|
||||
- 网格调用的最小写法是 `r := #Func(args);`。
|
||||
- 网格调用返回的不是最终值；用 `dupvalue(r)` 取回结果。
|
||||
- `timeout N` 后缀可直接接在网格调用后面。
|
||||
- 全局缓存函数的参数规格见 [../reference/catalog/system.md](../reference/catalog/system.md)；本页只保留缓存引用的运行时行为示例。
|
||||
- 写入和读取全局缓存成功时返回 `1`。
|
||||
- 从全局缓存取出的值，`ifCache(v)` 会返回 `1`。
|
||||
- 一旦对取出的缓存值做本地写入，它会立刻实例化；写入后 `ifCache(v)` 返回 `0`。
|
||||
- `checkGlobalCacheExpired(v)` 对同名缓存的最新引用返回 `0`；同名缓存被重置后，旧引用会变成过期状态并返回 `1`。
|
||||
- 全局缓存取出的值可以直接参与 `select`。
|
||||
|
||||
## 可直接照写示例
|
||||
|
||||
直接设置和读取系统参数：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
setSysParam("a", 123);
|
||||
setSysParam("b", "XYZ");
|
||||
writeLn(getSysParam("a"));
|
||||
writeLn(getSysParam("b"));
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- 依次输出 `123`、`XYZ`
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
123
|
||||
XYZ
|
||||
```
|
||||
|
||||
`sysParams[...]` 直接读写：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
sysParams["a"] := 321;
|
||||
sysParams["b"] := "QQ";
|
||||
writeLn(sysParams["a"]);
|
||||
writeLn(sysParams["b"]);
|
||||
writeLn(getSysParam("a"));
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- 依次输出 `321`、`QQ`、`321`
|
||||
- 说明 `sysParams[...]` 和 `getSysParam(...)` / `setSysParam(...)` 指向的是同一组运行时环境参数
|
||||
|
||||
沿用同一个 `TestDo.tsf`，看 `with array(...)` 的覆盖边界：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
代码块说明：多文件结构骨架；依赖函数文件查找路径，不是可直接复制的单文件最小示例。
|
||||
|
||||
```text
|
||||
// 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` 改成下面这样：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
代码块说明：多文件结构骨架；依赖函数文件查找路径，不是可直接复制的单文件最小示例。
|
||||
|
||||
```text
|
||||
// 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`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
writeLn(dupvalue(#AddOne(5)));
|
||||
|
||||
function AddOne(v);
|
||||
begin
|
||||
return v + 1;
|
||||
end;
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- `#AddOne(5)` 可以执行
|
||||
- `dupvalue(r)` 返回最终结果 `6`
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
6
|
||||
```
|
||||
|
||||
### 网格调用的 `timeout`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
writeLn(dupvalue(#AddOne(5) timeout 3000));
|
||||
|
||||
function AddOne(v);
|
||||
begin
|
||||
return v + 1;
|
||||
end;
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- `timeout 3000` 这种后缀写法可以通过并正常执行
|
||||
- 上例输出 `6`
|
||||
|
||||
### `setGlobalCache`、`getGlobalCache` 与 `ifCache`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
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]);
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- `setGlobalCache("PB_TEST_GC_BASIC", v1)` 返回 `1`
|
||||
- `getGlobalCache("PB_TEST_GC_BASIC", v2)` 返回 `1`
|
||||
- 取出的 `v2` 上 `ifCache(v2)` 返回 `1`
|
||||
- `v2` 长度是 `3`，内容是 `1,2,3`
|
||||
|
||||
### `checkGlobalCacheExpired`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
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));
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- 刚取出的缓存引用上，`checkGlobalCacheExpired(v)` 返回 `0`
|
||||
- 同名缓存被重新设置后，旧引用上的 `checkGlobalCacheExpired(v)` 返回 `1`
|
||||
|
||||
### 写入后会实例化
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
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]);
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- 刚取出时 `ifCache(v)` 返回 `1`
|
||||
- 对 `v[0]` 赋值后，`ifCache(v)` 立即返回 `0`
|
||||
- 写入后的本地值内容是 `100,2,3`
|
||||
|
||||
### 全局缓存参与 `select`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
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]);
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- 对缓存值做 `select` 可以正常执行
|
||||
- 返回结果的 `dataType` 是 `5`
|
||||
- 行数是 `3`
|
||||
- 排序后内容依次是 `(3,4)`、`(2,1)`、`(1,2)`
|
||||
|
||||
## 本页不生成的范围
|
||||
|
||||
- 网格超时触发错误时的完整边界
|
||||
- `getGlobalCacheInfo`、`listGlobalCache`、`listGlobalCacheRemoved`
|
||||
- 初始化 TSL、监控线程、回收策略与兼容旧系统方案
|
||||
|
||||
这些名称只作为边界提示，不作为本页可生成模板。
|
||||
|
||||
## 默认生成模板
|
||||
|
||||
最小运行时环境入口的默认骨架如下：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
setSysParam("a", 1);
|
||||
writeLn(getSysParam("a"));
|
||||
```
|
||||
|
||||
需要网格调用结果时，优先从下面这个模板起步：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
writeLn(dupvalue(#AddOne(5)));
|
||||
|
||||
function AddOne(v);
|
||||
begin
|
||||
return v + 1;
|
||||
end;
|
||||
```
|
||||
|
||||
需要缓存时，从 `setGlobalCache` / `getGlobalCache` 那一节选择模板。
|
||||
|
||||
## 禁止项
|
||||
|
||||
- 把系统参数页直接写成金融函数页。
|
||||
- 把 `#Func() with array(...)` 误判成也能直接套在本地函数 `Demo()` 后面。
|
||||
- 以为 `with array(...)` 改的是全局永久值，不会恢复外层原环境。
|
||||
- 把网格句柄直接当最终值用，而不做 `dupvalue(...)`。
|
||||
- 以为从全局缓存取出的值，本地写入后仍然保持缓存身份。
|
||||
- 以为旧缓存引用在同名缓存被重置后还会继续视为“未过期”。
|
||||
- `r := #Func(args);` 保存的是网格调用句柄；需要最终结果时继续写 `dupvalue(r)`。
|
||||
|
||||
代码块身份：反例 / 不可照写
|
||||
|
||||
```text
|
||||
r := Demo() with array("a": 11);
|
||||
|
||||
function Demo();
|
||||
begin
|
||||
return getSysParam("a");
|
||||
end;
|
||||
```
|
||||
|
||||
上面这种“本地函数后缀 `with`”写法不作为可写事实；常见报错是 `Statement missing terminator`，随后出现 `function compile error`。
|
||||
Reference in New Issue
Block a user