原子自增/自减 (LCC.kvdb.dict.incr)

声明

value, meta_or_err = LCC.kvdb.dict.incr(name, key, by?, init?, min?, max?, coerce?, timeout?)

参数

• name
  字符串型，词典名称（非空，最长 256 字节）
• key
  字符串型，键名（必须为合法 UTF-8，且非空）
• by
  整数型，可选；增减步长，默认 1，可为负数
• init
  整数型，可选；键不存在时的初始值，默认 0
• min
  整数型，可选；结果下限，超出时会被钳制
• max
  整数型，可选；结果上限，超出时会被钳制
• coerce
  布尔型，可选；为 true 时遇到非整数旧值会强制重置为 init，默认 false
• timeout
  数值型，可选；请求超时时间（秒），默认 60

返回值

• value
  数值型，自增后的结果；失败时为 nil
• meta_or_err
  表类型或字符串。成功时返回元信息表：
  • created：布尔型，本次是否新建键
  • coerced：布尔型，是否触发类型强制
  • clamped：布尔型，结果是否被钳制
  • clamp_reason：字符串，钳制原因（min/max）
  • original_value：数值型，旧值（若存在）
  • computed_value：数值型，按步长计算后的值
  • result_value：数值型，最终写入值 失败时返回错误描述字符串

说明

线程安全的原子计数器操作。
通过 min/max 可以限制结果区间，coerce 用于将非法旧值重置为 init。
调用失败时返回 nil, 错误信息。

示例

local value, meta = LCC.kvdb.dict.incr("计数器", "重试次数", 1, 0, 0, 5, true)
if value then
    LCC.log(1, "当前重试次数", value, meta.clamped and "已达上限" or "")
end