📦 deps(tsl): sync tsl-playbook from 5d73964d

Source-Commit: 5d73964db8
2026-08-14 17:15:41 +08:00
parent 5f4ca63966
commit 2f0d80da65
574 changed files with 47871 additions and 14463 deletions
@@ -166,3 +166,268 @@ end;
 // 输出：1
 // 输出：3
 ```
+
+## `makeWeakRef(obj)`
+
+声明：function
+
+为对象或函数创建弱引用，不支持的类型会抛出异常
+
+<!-- tags: 对象 弱引用 引用计数 生命周期 weak reference -->
+
+| 参数  | 类型             | 说明                   |
+| ----- | ---------------- | ---------------------- |
+| `obj` | object\|function | 支持弱引用的对象或函数 |
+
+返回：weak_object
+
+### 示例
+
+范例01：创建对象的弱引用
+
+```tsl
+source := new TStringList();
+source.append("A");
+weak := makeWeakRef(source);
+echo checkWeakRef(weak), "\n";
+// 输出：1
+```
+
+## `makeWeakRef(obj, result)`
+
+声明：function
+
+尝试为对象或函数创建弱引用，并通过输出参数报告是否成功
+
+<!-- tags: 对象 弱引用 安全创建 输出参数 weak reference try -->
+
+| 参数     | 类型             | 说明                       |
+| -------- | ---------------- | -------------------------- |
+| `obj`    | object\|function | 要创建弱引用的对象或函数   |
+| `result` | boolean          | 输出变量，创建成功时为真值 |
+
+返回：weak_object
+
+### 示例
+
+范例01：处理不支持弱引用的值
+
+```tsl
+weak := makeWeakRef(10, result);
+echo result, "\n";
+// 输出：0
+```
+
+## `weakRef(obj)`
+
+声明：function
+
+为对象或函数创建弱引用，是 `makeWeakRef` 的别名
+
+<!-- tags: 对象 弱引用 引用计数 生命周期 weak reference alias -->
+
+| 参数  | 类型             | 说明                   |
+| ----- | ---------------- | ---------------------- |
+| `obj` | object\|function | 支持弱引用的对象或函数 |
+
+返回：weak_object
+
+### 示例
+
+范例01：通过弱引用访问对象
+
+```tsl
+source := new TStringList();
+source.append("A");
+weak := weakRef(source);
+weak.append("B");
+echo weak.commaText, "\n";
+// 输出：A,B
+```
+
+## `weakRef(obj, result)`
+
+声明：function
+
+尝试为对象或函数创建弱引用，并通过输出参数报告是否成功
+
+<!-- tags: 对象 弱引用 安全创建 输出参数 weak reference try alias -->
+
+| 参数     | 类型             | 说明                       |
+| -------- | ---------------- | -------------------------- |
+| `obj`    | object\|function | 要创建弱引用的对象或函数   |
+| `result` | boolean          | 输出变量，创建成功时为真值 |
+
+返回：weak_object
+
+### 示例
+
+范例01：处理不支持弱引用的值
+
+```tsl
+weak := weakRef(10, result);
+echo result, "\n";
+// 输出：0
+```
+
+## `makeStrongRef(weak_obj)`
+
+声明：function
+
+从有效弱引用取得强引用，弱引用已经失效时会抛出异常
+
+<!-- tags: 对象 强引用 弱引用 恢复 获取 weak strong reference -->
+
+| 参数       | 类型        | 说明       |
+| ---------- | ----------- | ---------- |
+| `weak_obj` | weak_object | 有效弱引用 |
+
+返回：object
+
+### 示例
+
+范例01：从弱引用取得强引用
+
+```tsl
+source := new TStringList();
+source.append("A");
+weak := weakRef(source);
+strong := makeStrongRef(weak);
+strong.append("B");
+echo strong.commaText, "\n";
+// 输出：A,B
+```
+
+## `makeStrongRef(weak_obj, result)`
+
+声明：function
+
+尝试从弱引用取得强引用，并通过输出参数报告是否成功
+
+<!-- tags: 对象 强引用 弱引用 安全获取 输出参数 weak strong reference try -->
+
+| 参数       | 类型        | 说明                       |
+| ---------- | ----------- | -------------------------- |
+| `weak_obj` | weak_object | 要转换的弱引用             |
+| `result`   | boolean     | 输出变量，转换成功时为真值 |
+
+返回：object
+
+### 示例
+
+范例01：安全取得强引用
+
+```tsl
+source := new TStringList();
+source.append("A");
+weak := weakRef(source);
+strong := makeStrongRef(weak, result);
+echo result, ",", strong.commaText, "\n";
+// 输出：1,A
+```
+
+## `weakref_get(weak_obj)`
+
+声明：function
+
+从有效弱引用取得强引用，是 `makeStrongRef` 的别名
+
+<!-- tags: 对象 强引用 弱引用 恢复 获取 weak strong reference alias -->
+
+| 参数       | 类型        | 说明       |
+| ---------- | ----------- | ---------- |
+| `weak_obj` | weak_object | 有效弱引用 |
+
+返回：object
+
+### 示例
+
+范例01：从弱引用取得强引用
+
+```tsl
+source := new TStringList();
+source.append("A");
+weak := weakRef(source);
+strong := weakref_get(weak);
+strong.append("B");
+echo strong.commaText, "\n";
+// 输出：A,B
+```
+
+## `weakref_get(weak_obj, result)`
+
+声明：function
+
+尝试从弱引用取得强引用，并通过输出参数报告是否成功
+
+<!-- tags: 对象 强引用 弱引用 安全获取 输出参数 weak strong reference try alias -->
+
+| 参数       | 类型        | 说明                       |
+| ---------- | ----------- | -------------------------- |
+| `weak_obj` | weak_object | 要转换的弱引用             |
+| `result`   | boolean     | 输出变量，转换成功时为真值 |
+
+返回：object
+
+### 示例
+
+范例01：安全取得强引用
+
+```tsl
+source := new TStringList();
+source.append("A");
+weak := weakRef(source);
+strong := weakref_get(weak, result);
+echo result, ",", strong.commaText, "\n";
+// 输出：1,A
+```
+
+## `checkWeakRef(weak_obj)`
+
+声明：function
+
+返回弱引用的引用计数，有效对象已释放时返回 `-1`，参数不是弱引用时返回 `-2`
+
+<!-- tags: 对象 弱引用 检查 判断 引用计数 状态 weak reference -->
+
+| 参数       | 类型        | 说明           |
+| ---------- | ----------- | -------------- |
+| `weak_obj` | weak_object | 要检查的弱引用 |
+
+返回：integer
+
+### 示例
+
+范例01：检查有效弱引用
+
+```tsl
+source := new TStringList();
+weak := weakRef(source);
+echo checkWeakRef(weak), "\n";
+// 输出：1
+```
+
+## `weakref_check(weak_obj)`
+
+声明：function
+
+返回弱引用的引用计数，是 `checkWeakRef` 的别名
+
+<!-- tags: 对象 弱引用 检查 判断 引用计数 状态 weak reference alias -->
+
+| 参数       | 类型        | 说明           |
+| ---------- | ----------- | -------------- |
+| `weak_obj` | weak_object | 要检查的弱引用 |
+
+返回：integer
+
+### 示例
+
+范例01：检查有效弱引用
+
+```tsl
+source := new TStringList();
+weak := weakRef(source);
+echo weakref_check(weak), "\n";
+// 输出：1
+```