# Builtin - 全局缓存

## `getGlobalCache(name, out_value)`

声明：function

按名称读取全局缓存

<!-- tags: 全局缓存 读取缓存 获取缓存 cache get 读取 获取 缓存 缓存管理 -->

| 参数        | 类型   | 说明                                                                 |
| ----------- | ------ | -------------------------------------------------------------------- |
| `name`      | string | 全局缓存名称。                                                       |
| `out_value` | any    | 输出变量。数组或 Matrix 返回全局缓存引用；简单类型返回实例化后的值。 |

返回：Boolean，读取成功返回真，否则返回假。

### 示例

范例01：读取数组缓存

```tsl
key := "PB_DOC_GLOBAL_CACHE_READ";
source_data := array(1, 2, 3);
setGlobalCache(key, source_data);
ok := getGlobalCache(key, cached_data);
echo ok, "\n";
echo cached_data[0], ",", cached_data[1], ",", cached_data[2], "\n";
// 输出：
// 1
// 1,2,3
```

## `GetGlobalCacheInfo(value)`

声明：function

获取全局缓存引用的信息

<!-- tags: 全局缓存 缓存信息 引用计数 内存 过期 cache info 获取 查询 缓存 缓存管理 -->

| 参数    | 类型 | 说明                 |
| ------- | ---- | -------------------- |
| `value` | Obj  | 全局缓存的引用类型。 |

返回：Array，字段包括 `name`、`memsize`、`refs`、`tmexpired`、`createtm`、`endtm`、`expired` 和 `expiredtm`。

### 示例

范例01：读取全局缓存的名称

```tsl
key := "PB_DOC_GLOBAL_CACHE_INFO";
setGlobalCache(key, array(4, 5, 6));
getGlobalCache(key, cached_data);
info := GetGlobalCacheInfo(cached_data);
echo info["name"], "\n";
// 输出：PB_DOC_GLOBAL_CACHE_INFO
```

## `ifCache(value, level)`

声明：function

判断变量或单元格是否为全局缓存引用

<!-- tags: 全局缓存 判断缓存引用 类型判断 cache reference 判断 检查 缓存 缓存管理 -->

| 参数    | 类型    | 说明                                                                               |
| ------- | ------- | ---------------------------------------------------------------------------------- |
| `value` | Obj     | 待判断的数据。                                                                     |
| `level` | integer | 可选。类型识别函数的公共递归层级参数；正数检查全部层级，负数检查 `abs(level)` 层。 |

返回：Boolean 或 Boolean 数组。

### 示例

范例01：判断缓存引用在本地写入前后的状态

```tsl
echo ifCache(1), "\n";
setGlobalCache("PB_DOC_GLOBAL_CACHE_IF", array(7, 8));
getGlobalCache("PB_DOC_GLOBAL_CACHE_IF", cached_data);
echo ifCache(cached_data), "\n";
cached_data[0] := 70;
echo ifCache(cached_data), "\n";
// 输出：
// 0
// 1
// 0
```

## `ListGlobalCache()`

声明：function

列出现存的全局缓存信息及引用用户。需要高级权限 HighLevel 2 或系统权限

<!-- tags: 全局缓存 列出缓存 缓存管理 cache list 列出 列表 缓存 -->

返回：Array，现存全局缓存信息以及被引用的用户情况。

### 示例

范例01：获取现存全局缓存列表

```tsl
cache_list := ListGlobalCache();
echo dataType(cache_list), "\n";
// 输出：5
```

## `ListGlobalCacheRemoved()`

声明：function

列出被重置或过期的全局缓存信息及引用用户。需要高级权限 HighLevel 2 或系统权限

<!-- tags: 全局缓存 过期缓存 重置缓存 缓存管理 cache removed 列出 列表 缓存 -->

返回：Array，被重置或过期的全局缓存信息以及被引用的用户情况。

### 示例

范例01：获取已重置或过期的缓存列表

```tsl
removed_list := ListGlobalCacheRemoved();
echo dataType(removed_list), "\n";
// 输出：5
```

## `setGlobalCache(name, value, end_t)`

声明：function

设置全局缓存

<!-- tags: 全局缓存 写入缓存 设置缓存 过期时间 cache set 设置 修改 缓存 缓存管理 -->

| 参数    | 类型      | 说明                                         |
| ------- | --------- | -------------------------------------------- |
| `name`  | string    | 全局缓存名称。                               |
| `value` | any       | 全局缓存值；不能使用对象等无法全局化的类型。 |
| `end_t` | TDateTime | 可选。全局缓存的过期时间。                   |

返回：Boolean，设置成功返回真，否则返回假。

### 示例

范例01：写入一个简单值

```tsl
ok := setGlobalCache("PB_DOC_GLOBAL_CACHE_SET", 300);
echo ok, "\n";
// 输出：1
```