nginx的共享字典项api（操作方法）

nginx的共享内存，称为共享字典项，对于所有的worker进程都可见，是一种全局变量。

备注一下内容中的 [] 是 备注。

源码分析文档：https://www.codercto.com/a/9488.html

git 文档 ：https://github.com/openresty/lua-nginx-module#ngxshareddictget

设置全局字典项，在http 配置块下：

lua_shared_dict cats[字典项名称] 12M[内存大小];

1、 ngx.shared.DICT.get

语法：value, flags = ngx.shared.DICT:get(key)

获取共享内存上key对应的值。如果key不存在，或者key已经过期，将会返回nil；如果出现错误，那么将会返回nil以及错误信息。

local cats = ngx.shared.cats local value, flags = cats.get(cats, "Marry")

等价于

local cats = ngx.shared.cats local value, flags = cats:get("Marry")

返回列表中的flags，是在ngx.shared.DICT.set方法中设置的值，默认值为0. 如果设置的flags为0，那么在这里flags的值将不会被返回。

2、 ngx.shared.DICT.get_stale

语法：value, flags, stale = ngx.shared.DICT:get_stale(key) 与get方法类似，区别在于该方法对于过期的key也会返回，第三个返回参数表明返回的key的值是否已经过期，true表示过期，false表示没有过期。

3、 ngx.shared.DICT.set

语法：success, err, forcible = ngx.shared.DICT:set(key, value, exptime?, flags?)

无条件”地往共享内存上插入key-value对，这里讲的“无条件”指的是不管待插入的共享内存上是否已经存在相同的key。三个返回值的含义：

success：成功插入为true，插入失败为false

err：操作失败时的错误信息，可能类似"no memory"

forcible：true表明需要通过强制删除（LRU算法）共享内存上其他字典项来实现插入，false表明没有删除共享内存上的字典项来实现插入。

第三个参数exptime表明key的有效期时间，单位是秒（s），默认值为0，表明永远不会过期；flags参数是一个用户标志值，会在调用get方法时同时获取得到。

local cats = ngx.shared.cats
local succ, err, forcible = cats.set(cats, "Marry", "it is a nice cat!")
 
等价于
 
local cats = ngx.shared.cats
local succ, err, forcible = cats:set("Marry", "it is a nice cat!")

4、 ngx.shared.DICT.safe_set

语法：ok, err = ngx.shared.DICT:safe_set(key, value, exptime?, flags?)

与set方法类似，区别在于不会在共享内存用完的情况下，通过强制删除（LRU算法）的方法实现插入。如果内存不足，会直接返回nil和err信息"no memory"

注意：

set和safe_set共同点是：如果待插入的key已经存在，那么key对应的原来的值会被新的value覆盖！

5、　 ngx.shared.DICT.add

语法：success, err, forcible = ngx.shared.DICT:add(key, value, exptime?, flags?)

与set方法类似，与set方法区别在于不会插入重复的键（可以简单认为add方法是set方法的一个子方法），如果待插入的key已经存在，将会返回nil和和err="exists"

6、 　ngx.shared.DICT.safe_add

语法：ok, err = ngx.shared.DICT:safe_add(key, value, exptime?, flags?)

与safe_set方法类似，区别在于不会插入重复的键（可以简单认为safe_add方法是safe_set方法的一个子方法），如果待插入的key已经存在，将会返回nil和和err="exists"

7、 ngx.shared.DICT.replace

语法：success, err, forcible = ngx.shared.DICT:replace(key, value, exptime?, flags?)

与set方法类似，区别在于只对已经存在的key进行操作（可以简单认为replace方法是set方法的一个子方法），如果待插入的key在字典上不存在，将会返回nil和错误信息"not found"

8、 ngx.shared.DICT.delete

　　语法：ngx.shared.DICT:delete(key)

　　无条件删除指定的key-value对，其等价于

　　ngx.shared.DICT:set(key, nil)

9、  ngx.shared.DICT.incr

　　语法：newval, err = ngx.shared.DICT:incr(key, value)

　　对key对应的值进行增量操作，增量值是value，其中value的值可以是一个正数，0，也可以是一个负数。value必须是一个Lua类型中的number类型，否则将会返回nil　　和"not a number"；key必须是一个已经存在于共享内存中的key，否则将会返回nil和"not found".

10、  ngx.shared.DICT.flush_all

　　语法：ngx.shared.DICT:flush_all()

　　清除字典上的所有字段，但不会真正释放掉字段所占用的内存，而仅仅是将每个字段标志为过期。

11、 ngx.shared.DICT.flush_expired

　　语法：flushed = ngx.shared.DICT:flush_expired(max_count?)

　　清除字典上过期的字段，max_count表明上限值，如果为0或者没有给出，表明需要清除所有过期的字段，返回值flushed是实际删除掉的过期字段的数目。

　　注意：

　　与flush_all方法的区别在于，该方法将会释放掉过期字段所占用的内存。

12、 ngx.shared.DICT.get_keys　　

　　语法：keys = ngx.shared.DICT:get_keys(max_count?)

　　从字典上获取字段列表，个数为max_count，如果为0或没有给出，表明不限定个数。默认值是1024个

　　注意：

　　强烈建议在调用该方法时，指定一个max_count参数，因为在keys数量很大的情况下，如果不指定max_count的值，可能会导致字典被锁定，从而阻塞试图访问字典的worker进程。

13、  ngx.shared.DICT.flush_keys

　　语法： ngx.shared.DICT:flush_keys(num, time)

　　从字典项获取 key ,数量为 num , 时间 为 time 有效。 指定 num 为了 保证处理数据不会被撑爆内存。