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

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

## 本篇职责

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

## 核心规则

本页示例只说明运行时上下文语法中的调用位置和源码外形。API 的精确签名、参数、返回行为、平台 scope、目标环境或解释器可用性必须使用 `tsl-api-reference` skill 重新核对，不能由本页示例反推。

- 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` / `getSysParam` / `sysParams[...]` 基础读写

<!-- tags: 系统参数, 读写运行参数, 环境设置, 全局设置项 -->

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

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

```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 *`

<!-- tags: 临时改参数, 局部生效, 一段代码内有效, 块内覆盖 -->

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

```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 **`

<!-- tags: 嵌套覆盖, 深层块环境, 多层 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 **` 不继承未传入的外层系统参数，并且块结束后恢复外层系统参数

### 后缀 `with array(...)`：网格调用的临时覆盖

<!-- tags: 调用时临时改参数, 单次覆盖, 调用完恢复 -->

`#Func(...) with array(...)` 在一次网格调用里临时覆盖系统参数，调用结束后恢复外层原值。下面用一个 `TestDo.tsf` 演示覆盖边界：

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

```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`

<!-- tags: 网格调用, 分布式执行, 井号调用, 取回结果 -->

网格调用函数：

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

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

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

结果说明：

- `#AddOne(5)` 可以执行
- `dupvalue(#AddOne(5))` 返回最终结果 `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`

<!-- tags: 超时, 限制执行时间, 多久不返回就断 -->

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

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

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

结果说明：

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

### `setGlobalCache`、`getGlobalCache` 与 `ifCache`

<!-- tags: 全局缓存, 缓存数据, 跨脚本共享, 存起来下次用 -->

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

```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(key, value)` / `getGlobalCache(key, out_var)` 的最小调用形态；完整参数规格（含过期时间等可选参数）用 `tsl-api-reference` skill 按名查询

### `checkGlobalCacheExpired`

<!-- tags: 缓存过期, 缓存失效判断, 什么时候要重算 -->

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

```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`

### 缓存值本地写入后会实例化

<!-- tags: 改缓存内容, 缓存副本, 写回不影响原缓存 -->

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

```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`

<!-- tags: 对缓存做查询, 缓存当表查 -->

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

```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(key, value)` 写入、`getGlobalCache(key, out_var)` 读取。

## 禁止项

- 把系统参数页直接写成金融函数页。
- 把 `#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`。