📝 docs(tsl): rebuild canonical syntax and routing manual
This commit is contained in:
@@ -0,0 +1,205 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user