# Runtime Services And Global Cache

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

手册位置：第 30 篇，共 32 篇。上一篇：[29_ts_sql_advanced.md](29_ts_sql_advanced.md)。下一篇：[31_complex_and_weakref.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`

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

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

已验证运行结果：

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

### 网格调用的 `timeout`

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

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

已验证运行结果：

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

### `SetGlobalCache`、`GetGlobalCache` 与 `ifcache`

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

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

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

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

### 写入后会实例化

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

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

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

```tsl
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、监控线程、回收策略与兼容旧系统方案

## 最小可编译示例

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

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

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

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

## 常见误写

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

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

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

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

## 跳转指引

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