全局字典相关函数
更新时间 2024-07-22 18:11:17
最近更新时间: 2024-07-22 18:11:17
本文简述全局字典相关函数的语法、作用、入参、返回值、示例。
ctyun.dict.DICT.set
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | success, err, forcible = DICT:set(key_name, value, ttl?, flags?) |
| 作用 | 在全局字典ctyun.dict.DICT 中设置一个键值对。 其中value可以是Lua布尔值、数字、字符串，或nil类型的，不可以是table类型的。 |
| 入参 | key_name：设置内容的键。 value：设置内容的值。 ttl：设置key/value的有效期（单位是秒），为可选参数，默认是不过期的。如果为0（默认）则表示永远不失效。 flags: 用来做用户标识，可以标识set操作的执行者，默认是0。只能设置number类型; 为可选参数。 |
| 返回值 | success：布尔值，用来表示是否成功set。 err：如果success的值是false，就会将错误信息存放在err中。 forcible：布尔值，用来表示是否有数据被强制删除。在存储数据的过程中，如果内存空间不够就会使用LRU算法清除数据，此时，forcible为true。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local succ, err, forcible = cats:set("Marry", "it is a nice cat!")
ctyun.dict.DICT.safe_set
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | success, err, forcible = DICT:safe_set(key_name, value, ttl?, flags?) |
| 作用 | 与set类似，但在内存不足的情况下，它不会覆盖已经存在且没有过期的数据，而会报“no memory”错误并返回nil。 |
| 入参 | key_name：设置内容的键。 value：设置内容的值。 ttl：设置key/value的有效期（单位是秒），为可选参数，默认是不过期的。如果为0（默认）则表示永远不失效。 flags: 用来做用户标识，可以标识set操作的执行者，默认是0。只能设置number类型; 为可选参数。 |
| 返回值 | success：布尔值，用来表示是否成功set。 err：如果success的值是false，就会将错误信息存放在err中。 forcible：布尔值，用来表示是否有数据被强制删除。在存储数据的过程中，如果内存空间不够就会使用LRU算法清除数据，此时，forcible为true。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local succ, err, forcible = cats:safe_set("Marry", "it is a nice cat!")
ctyun.dict.DICT.get
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | value, flags = DICT:get(key_name) |
| 作用 | 在全局字典ctyun.dict.DICT中设置一个键值对。获取指定key对应的value，value的数据类型与存储时的原始数据类型一致，但如果key不存在或过期就返回nil。 |
| 入参 | key_name：要获取内容的键值。 |
| 返回值 | value: key对应的value。 flags: 用来获取是否对用户做了标识，一般在set时都会加入标识，如果没有，则默认为0。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local value, _ = cats:get("Marry")
ctyun.dict.DICT.get_stale
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | value, flags, stale = DICT:get_stale(key_name) |
| 作用 | 与get类似，但返回的是过期的值，过期的值无法保证一直存在，如当内存不够时会被自动清理。 |
| 入参 | key_name：要获取内容的键值。 |
| 返回值 | value: key对应的value。 flags: 用来获取是否对用户做了标识，一般在set时都会加入标识，如果没有，则默认为0。 stale: 代表获取的value是否已经过期，如果是，则返回true。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local value, _ = cats:get_stale("Marry")
ctyun.dict.DICT.add
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | success, err, forcible = DICT:add(key_name, value, ttl?, flags?) |
| 作用 | 与set类似，但如果key在缓存里存在且没有过期就不会执行add指令，此时err会返回“exist”；如果key不存在或已过期，则会执行add指令并把key/value的值存入共享内存中。 |
| 入参 | key_name：设置内容的键。 value：设置内容的值。 ttl：设置key/value的有效期（单位是秒），为可选参数，默认是不过期的。如果为0（默认）则表示永远不失效。 flags: 用来做用户标识，可以标识set操作的执行者，默认是0。只能设置number类型; 为可选参数。 |
| 返回值 | success：布尔值，用来表示是否成功set。 err：如果success的值是false，就会将错误信息存放在err中。 forcible：布尔值，用来表示是否有数据被强制删除。在存储数据的过程中，如果内存空间不够就会使用LRU算法清除数据，此时，forcible为true。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local succ, err, forcible = cats:add("Marry", "it is a nice cat!")
ctyun.dict.DICT.safe_add
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | success, err, forcible = DICT:safe_add(key_name, value, ttl?, flags?) |
| 作用 | 与set类似，但在内存不足的情况下，它不会覆盖已经存在且没有过期的数据，而会报“no memory”错误并返回nil。 |
| 入参 | key_name：设置内容的键。 value：设置内容的值。 ttl：设置key/value的有效期（单位是秒），为可选参数，默认是不过期的。如果为0（默认）则表示永远不失效。 flags: 用来做用户标识，可以标识set操作的执行者，默认是0。只能设置number类型; 为可选参数。 |
| 返回值 | success：布尔值，用来表示是否成功set。 err：如果success的值是false，就会将错误信息存放在err中。 forcible：布尔值，用来表示是否有数据被强制删除。在存储数据的过程中，如果内存空间不够就会使用LRU算法清除数据，此时，forcible为true。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local succ, err, forcible = cats:safe_add("Marry", "it is a nice cat!")
ctyun.dict.DICT.replace
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | success, err, forcible = DICT:replace(key_name, value, ttl?, flags?) |
| 作用 | 和set类似，但只有当key存在时，才会把key/value的值存入共享内存中（key过期属于不存在的情况）。 |
| 入参 | key_name：设置内容的键。 value：设置内容的值。 ttl：设置key/value的有效期（单位是秒），为可选参数，默认是不过期的。如果为0（默认）则表示永远不失效。 flags: 用来做用户标识，可以标识set操作的执行者，默认是0。只能设置number类型; 为可选参数。 |
| 返回值 | success：布尔值，用来表示是否成功set。 err：如果success的值是false，就会将错误信息存放在err中。 forcible：布尔值，用来表示是否有数据被强制删除。在存储数据的过程中，如果内存空间不够就会使用LRU算法清除数据，此时，forcible为true。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local succ, err, forcible = cats:replace("Marry", "it is a nice cat!")
ctyun.dict.DICT.delete
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | DICT:delete(key_name) |
| 作用 | 删除指定的key。 |
| 入参 | key_name：设置内容的键。 |
| 返回值 | 无。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
cats:delete("Marry")
ctyun.dict.DICT.incr
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | newval, err, forcible = DICT:incr(key_name, value, init?, ttl?) |
| 作用 | 让指定key的值递增，步长是value。适合用来在请求时做计数操作。newval是数字累加后的值。如果key不存在，并且init参数为空，则请求会返回“not found”并赋值给err；如果key不存在，并且init是number类型，那么会创建1个init+value的新key。 **注意：**这里的key、value、init，在正常情况下都应该是number类型。 |
| 入参 | key_name：设置内容的键。 value：设置内容的值。 init：设置初始计数值。 ttl: 设置key/value的有效期（单位是秒），为可选参数，默认是不过期的。如果为0（默认）则表示永远不失效。 |
| 返回值 | newval：数字累加后的值。 err：如果success的值是false，就会将错误信息存放在err中。 forcible：布尔值，用来表示是否有数据被强制删除。在存储数据的过程中，如果内存空间不够就会使用LRU算法清除数据，此时，forcible为true。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local newval, err, forcible = cats:incr("count", 1, 0, 3)
-- newval got 1
ctyun.sleep(3)
local val, err = cats:get("count")
-- val got nil
ctyun.dict.DICT.lpush
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | length, err = DICT:lpush(key_name, value) |
| 作用 | 消息队列操作：将string或number从头部插入key的列表中，并返回列表元素的个数。若key不存在则先创建key，存在但不是列表返回nil且err为“value not a list”。 |
| 入参 | key_name：设置内容的键。 value：设置内容的值。 |
| 返回值 | length：返回列表元素的个数。 err：将错误信息存放在err中。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local length, err = cats:lpush("Marry", 1)
ctyun.dict.DICT.rpush
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | length, err = DICT:rpush(key_name, value) |
| 作用 | 消息队列操作：与lpush类似，只是元素会从尾部插入。 |
| 入参 | key_name：设置内容的键。 value：设置内容的值。 |
| 返回值 | length：返回列表元素的个数。 err：将错误信息存放在err中。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local length, err = cats:rpush("Marry", 1)
ctyun.dict.DICT.lpop
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | value, err = DICT:lpop(key_name) |
| 作用 | 消息队列操作：移除并返回key列表的第一个值；若key不存在则返回nil，key存在但不是列表则返回nil且err为“value not a list”。 |
| 入参 | key_name：设置内容的键。 |
| 返回值 | value：设置内容的值。 err：将错误信息存放在err中。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local value, err = cats:lpop("Marry")
ctyun.dict.DICT.rpop
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | value, err = DICT:rpop(key_name) |
| 作用 | 消息队列操作：与lpop类似，只是元素会从尾部弹出。 |
| 入参 | key_name：设置内容的键。 |
| 返回值 | value：设置内容的值。 err：将错误信息存放在err中。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local value, err = cats:rpop("Marry")
ctyun.dict.DICT.llen
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | len, err = DICT:llen(key_name) |
| 作用 | 消息队列操作：返回各项制度为key_name的列表的元素数量。若key不存在则返回0，若key存在但不是列表返回nil且err为“value not a list”。 |
| 入参 | key_name：设置内容的键。 |
| 返回值 | len：列表的元素数量。 err：将错误信息存放在err中。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local len, err = cats:llen("Marry")
ctyun.dict.DICT.ttl
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | ttl, err = DICT:ttl(key_name) |
| 作用 | 获取共享内存中的key的有效期。 |
| 入参 | key_name：设置内容的键。 |
| 返回值 | ttl：key的有效期。 err：将错误信息存放在err中。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local ttl, err = cats:ttl("Marry")
ctyun.dict.DICT.expire
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | success, err = DICT:expire(key_name, exptime) |
| 作用 | 修改共享内存中的key的有效期。 |
| 入参 | key_name：设置内容的键。 exptime: 要更新的有效期时间值。 |
| 返回值 | success：布尔类型，是否成功。 err：将错误信息存放在err中。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local ok, err = cats:expire("Marry", 60)
ctyun.dict.DICT.flush_all
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | number = DICT:flush_all() |
| 作用 | 清空共享内存中的所有数据，方法是让所有的数据都过期，这意味着虽然可以用get_stale的方式去读取数据，但不一定会有值存在。 |
| 入参 | 无。 |
| 返回值 | 无。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
cats:flush_all()
ctyun.dict.DICT.flush_expired
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | number = DICT:flush_expired(max_count?) |
| 作用 | 清空共享内存中所有过期的数据，方法是释放掉这些内存，彻底清除数据，并返回所清除数据的数量。 |
| 入参 | max_count: 可选参数，如果不设置此参数或设为0，则会清除全部过期数据；如果参数值大于0，则会清除相应数量的数据。 |
| 返回值 | number: 返回实际已刷新的项目数。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local number = cats:flush_expired()
ctyun.dict.DICT.get_keys
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | keys = DICT:get_keys(max_count?) |
| 作用 | 获取共享内存中的全部已保存的key列表，返回的是table类型的数据。 |
| 入参 | max_count: 设置的是需要返回的数据的数量，默认是1024。如果设置为0，则表示返回全部数据。在实际运用中要尽量避免设置为0，因为如果数据量非常大，此操作会阻塞所有访问这个共享内存数据的worker进程。 |
| 返回值 | keys : 返回key列表。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local keys = cats:get_keys()
for _, key_name in pairs(keys) do
local value = cats:get(key_name)
end
ctyun.dict.DICT.free_space
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | free_capacity_bytes = DICT:free_space() |
| 作用 | 确认共享内存的剩余空间大小。 |
| 入参 | 无。 |
| 返回值 | free_capacity_bytes: 剩余空间大小。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local free_capacity_bytes = cats:free_space()
ctyun.dict.DICT.capacity
函数信息详见下表：
| 项目 | 描述 |
|---|---|
| 语法 | capacity_bytes = DICT:capacity() |
| 作用 | 确认共享内存的容量大小。 |
| 入参 | 无。 |
| 返回值 | capacity_bytes: 容量。 |
示例：
---假设全局字典名称为cats
local cats = ctyun.dict.cats
local capacity_bytes = cats:capacity()
注意示例中DICT为全局定义共享内存名称，需在控制台预先定义。
