原子自增/自減 (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