Squashed 'docs/standards/playbook/' changes from c3f8137..25d895d
25d895d 🐛 fix(gitea_workflow): clean up temp repos after job steps 2bc3b11 🐛 fix(gitea_workflow): clean up temporary repo dirs in workflows 98c3f30 📝 docs(agent_rules): allow plan execution on current branch 16c7230 📝 docs(prompts): define custom verify layering 8efc4dd 🐛 fix(skills): quote commit-message description bc8498f 🐛 fix(ci): install tomli for gitea tests 55cda3b 🐛 fix(tests): report missing toml parser clearly c0729c7 🐛 fix(playbook): import Optional for cli compatibility 63e24bf 📦 deps(skills): sync thirdparty skills d2f9356 🐛 fix(ci): isolate gitea workflow repos 588b81d 🐛 fix(ci): inline gitea workflow bootstrap e0b1c3a ♻️ refactor(skills): standardize first-party skill contracts 2c5050d ♻️ refactor(skills): rename repo skills source dir f049dfb 📦 deps(skills): drop duplicate first-party superpowers skills 234b335 ✨ feat(workflow): add superpowers planning and execution state tracking c1702a6 📝 docs(markdown): format tracked markdown and drop stale templates 2325409 📝 docs(markdown): clarify optional markdownlint usage 214c44e 🔧 chore(markdown): add markdownlint baseline and lint fixes a22b324 📝 docs(templates): add execution and memory-bank prompt templates 223a797 📝 docs(templates): update README for Claude Code and current features 4ac8672 📝 docs: simplify README + platform-agnostic tools + auto-create local rules 2431c9d 📝 docs: add claude_md config and use cross-platform paths d64b248 📝 docs: fix README.md inaccuracies and add Claude Code info c8d6bf2 🐛 fix(playbook): use relative paths in CLAUDE.md when not at project root 6518f0f ✨ feat(playbook): auto-create CLAUDE.md with path discovery 6ec9a45 ✨ feat(skills): add skill_link symlink support + platform-agnostic prompt 9f8b6b5 📝 docs: update README and config example for Claude Code support 79cff6c 📝 docs(skills): add Claude Code platform support 452c6f5 ✨ feat(playbook): auto-inject AGENTS.md into CLAUDE.md e1dbf3c 🐛 fix(skills): remove dual-path from commit-message skill f3a7259 🔧 chore(ci): use prepare_repo.sh in both workflows da08212 🔧 chore(ci): extract prepare_repo.sh and clean up workflows 7ade85e 🗑️ remove(tsl): drop syntax_book/, data/ source and build script f94dba0 ♻️ refactor(skills): update playbook.py and tests for thirdparty/ layout b3df412 ♻️ refactor(skills): separate thirdparty skills into thirdparty/ subdirectory 64950e7 📦 deps(skills): sync thirdparty skills a2e3cb0 ✨ feat(playbook): add no_backup deploy controls 8609d59 🐛 fix(docs): repair reference catalog source links 956da11 🐛 fix(playbook): publish hidden ci test fixes 3f67754 📦 deps(skills): sync thirdparty skills 08ca87b 📦 deps(skills): add karpathy thirdparty sync 96b705b 📝 docs(tsl): rebuild canonical syntax and routing manual 3ed5052 📦 deps(skills): sync thirdparty skills 60108dd 📦 deps(skills): sync thirdparty skills da85d4e 🐛 fix(thirdparty): prune nested project snapshots a2a697e 📦 deps(skills): sync thirdparty skills 9df610a 🐛 fix(thirdparty): exclude duplicated superpowers skills 33dd5bb 🐛 fix(thirdparty): preserve optional manifest fields 91b0ea7 🐛 fix(thirdparty): preserve manifest during snapshot update 2e26f98 🔧 chore(thirdparty): generalize skills sync pipeline 5b9c1e3 📦 deps(skills): sync superpowers 2f2d34a 📝 docs(readme): normalize subtree command spacing 62db7db 🐛 fix(ci): serialize superpowers update and sync 3463223 🐛 fix(ci): use literal superpowers sync paths 48f6de8 📦 deps(skills): sync superpowers 4b23529 🔧 chore(ci): merge superpowers update and sync workflow a56d75b 📦 deps(skills): sync superpowers 84bcefa 🔧 chore(ci): use ci[bot] commit author name 00a07e5 📦 deps(skills): sync superpowers 7b84daf 🐛 fix(templates): enforce main loop progress tracking 51373d7 🔧 chore(ci): automate superpowers sync workflow eaaa39c 🐛 fix(ci): prevent stale superpowers sync from restoring skills block 79755c6 📦 deps(skills): sync superpowers 836d878 📦 deps(skills): sync superpowers 8216c9f 📦 deps(skills): sync superpowers 9439505 🐛 fix(playbook): address reported repo issues git-subtree-dir: docs/standards/playbook git-subtree-split: 25d895d8b3f56624ccfe99ad7289e9eb49e0f316
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