ci[bot]
@@ -0,0 +1,426 @@
|
||||
# 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)、[../codegen/dotnet/datawarehouse/](../codegen/dotnet/datawarehouse/)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../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](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 *, 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()` 这类金融上下文参数，统一到 [../codegen/dotnet/datawarehouse/](../codegen/dotnet/datawarehouse/) 查函数事实。
|
||||
- 网格调用的最小写法是 `r := #Func(args);`。
|
||||
- 网格调用返回的不是最终值；用 `dupvalue(r)` 取回结果。
|
||||
- `timeout N` 后缀可直接接在网格调用后面。
|
||||
- 全局缓存函数的参数规格见 [../codegen/builtin/system/runtime.md](../codegen/builtin/system/runtime.md) 和 [../codegen/builtin/base/type_conversion.md](../codegen/builtin/base/type_conversion.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(...)` 指向的是同一组运行时环境参数
|
||||
|
||||
### 块环境 `with *`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
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` 使用当前所有系统参数：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
setSysParam("a", 10);
|
||||
setSysParam("b", 20);
|
||||
with *, SysParamArray do
|
||||
begin
|
||||
writeLn(getSysParam("a"));
|
||||
writeLn(getSysParam("b"));
|
||||
end
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
10
|
||||
20
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `SysParamArray` 是特殊关键字，表示引用当前所有系统参数
|
||||
- `with *, SysParamArray do` 把当前系统参数作为块环境传入
|
||||
- 这是服务端环境的常用写法，用于保持系统参数上下文
|
||||
|
||||
### 块环境 `with **`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
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(...)` 的覆盖边界：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
代码块说明：多文件结构骨架；依赖函数文件查找路径，不是可直接复制的单文件最小示例。
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
网格调用数组表达式：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
items := array(1, 2, 3, 4, 5);
|
||||
grid_result := #(items * 2);
|
||||
writeLn(tostn(dupvalue(grid_result)));
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
array(2,4,6,8,10)
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `#(表达式)` 可以对表达式进行网格计算
|
||||
- `#(items * 2)` 返回网格句柄
|
||||
- `dupvalue(grid_result)` 取回最终结果数组
|
||||
- 网格计算常用于大规模数组的分布式并行运算
|
||||
|
||||
### 网格调用的 `timeout`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
writeLn(dupvalue(#AddOne(5) timeout 3000));
|
||||
|
||||
function AddOne(v);
|
||||
begin
|
||||
return v + 1;
|
||||
end;
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- `timeout 3000` 这种后缀写法可以通过并正常执行
|
||||
- 上例输出 `6`
|
||||
|
||||
### `setGlobalCache`、`getGlobalCache` 与 `ifCache`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
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`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
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`
|
||||
|
||||
### 写入后会实例化
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
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`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
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 ...}` 包含文件指令
|
||||
|
||||
这些名称只作为边界提示，不作为本页可生成模板。
|
||||
|
||||
## 默认生成模板
|
||||
|
||||
最小运行时环境入口的默认骨架如下：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```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 *` 误判成会自动恢复外层系统参数。
|
||||
- 以为 `with array(...)` 改的是全局永久值，不会恢复外层原环境。
|
||||
- 把网格句柄直接当最终值用，而不做 `dupvalue(...)`。
|
||||
- 以为从全局缓存取出的值，本地写入后仍然保持缓存身份。
|
||||
- 以为旧缓存引用在同名缓存被重置后还会继续视为“未过期”。
|
||||
- `r := #Func(args);` 保存的是网格调用句柄；需要最终结果时继续写 `dupvalue(r)`。
|
||||
|
||||
代码块身份：反例 / 不可照写
|
||||
|
||||
```tsl
|
||||
cached_result := 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