Skip to content

Commit 1d01a6d

Browse files
thibaultchaagentzh
thibaultcha
authored and
agentzh
committed
doc: documented the shdict:ttl() and shdict:expire() API functions.
Signed-off-by: Yichun Zhang (agentzh) <agentzh@gmail.com>
1 parent 37cbafe commit 1d01a6d

File tree

2 files changed

+150
-0
lines changed

2 files changed

+150
-0
lines changed

‎README.markdown‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3191,6 +3191,8 @@ Nginx API for Lua
31913191
* [ngx.shared.DICT.lpop](#ngxshareddictlpop)
31923192
* [ngx.shared.DICT.rpop](#ngxshareddictrpop)
31933193
* [ngx.shared.DICT.llen](#ngxshareddictllen)
3194+
* [ngx.shared.DICT.ttl](#ngxshareddictttl)
3195+
* [ngx.shared.DICT.expire](#ngxshareddictexpire)
31943196
* [ngx.shared.DICT.flush_all](#ngxshareddictflush_all)
31953197
* [ngx.shared.DICT.flush_expired](#ngxshareddictflush_expired)
31963198
* [ngx.shared.DICT.get_keys](#ngxshareddictget_keys)
@@ -6198,6 +6200,8 @@ The resulting object `dict` has the following methods:
61986200
* [lpop](#ngxshareddictlpop)
61996201
* [rpop](#ngxshareddictrpop)
62006202
* [llen](#ngxshareddictllen)
6203+
* [ttl](#ngxshareddictttl)
6204+
* [expire](#ngxshareddictexpire)
62016205
* [flush_all](#ngxshareddictflush_all)
62026206
* [flush_expired](#ngxshareddictflush_expired)
62036207
* [get_keys](#ngxshareddictget_keys)
@@ -6543,6 +6547,82 @@ See also [ngx.shared.DICT](#ngxshareddict).
65436547

65446548
[Back to TOC](#nginx-api-for-lua)
65456549

6550+
ngx.shared.DICT.ttl
6551+
-------------------
6552+
**syntax:** *ttl, err = ngx.shared.DICT:ttl(key)*
6553+
6554+
**context:** *init_by_lua&#42;, set_by_lua&#42;, rewrite_by_lua&#42;, access_by_lua&#42;, content_by_lua&#42;, header_filter_by_lua&#42;, body_filter_by_lua&#42;, log_by_lua&#42;, ngx.timer.&#42;, balancer_by_lua&#42;, ssl_certificate_by_lua&#42;, ssl_session_fetch_by_lua&#42;, ssl_session_store_by_lua&#42;*
6555+
6556+
**requires:** `resty.core.shdict` or `resty.core`
6557+
6558+
Retrieves the remaining TTL (time-to-live in seconds) of a key-value pair in the shm-based dictionary [ngx.shared.DICT](#ngxshareddict). Returns the TTL as a number if the operation is successfully completed or `nil` and an error message otherwise.
6559+
6560+
If the key does not exist (or has already expired), this method will return `nil` and the error string `"not found"`.
6561+
6562+
The TTL is originally determined by the `exptime` argument of the [set](#ngxshareddictset), [add](#ngxshareddictadd), [replace](#ngxshareddictreplace) (and the likes) methods. It has a time resolution of `0.001` seconds. A value of `0` means that the item will never expire.
6563+
6564+
Example:
6565+
6566+
```lua
6567+
6568+
require "resty.core"
6569+
6570+
local cats = ngx.shared.cats
6571+
local succ, err = cats:set("Marry", "a nice cat", 0.5)
6572+
6573+
ngx.sleep(0.2)
6574+
6575+
local ttl, err = cats:ttl("Marry")
6576+
ngx.say(ttl) -- 0.3
6577+
```
6578+
6579+
This feature was first introduced in the `v0.10.11` release.
6580+
6581+
**Note:** This method requires the `resty.core.shdict` or `resty.core` modules from the [lua-resty-core](https://github.com/openresty/lua-resty-core) library.
6582+
6583+
See also [ngx.shared.DICT](#ngxshareddict).
6584+
6585+
[Back to TOC](#nginx-api-for-lua)
6586+
6587+
ngx.shared.DICT.expire
6588+
----------------------
6589+
**syntax:** *success, err = ngx.shared.DICT:expire(key, exptime)*
6590+
6591+
**context:** *init_by_lua&#42;, set_by_lua&#42;, rewrite_by_lua&#42;, access_by_lua&#42;, content_by_lua&#42;, header_filter_by_lua&#42;, body_filter_by_lua&#42;, log_by_lua&#42;, ngx.timer.&#42;, balancer_by_lua&#42;, ssl_certificate_by_lua&#42;, ssl_session_fetch_by_lua&#42;, ssl_session_store_by_lua&#42;*
6592+
6593+
**requires:** `resty.core.shdict` or `resty.core`
6594+
6595+
Updates the `exptime` (in second) of a key-value pair in the shm-based dictionary [ngx.shared.DICT](#ngxshareddict). Returns a boolean indicating success if the operation completes or `nil` and an error message otherwise.
6596+
6597+
If the key does not exist, this method will return `nil` and the error string `"not found"`.
6598+
6599+
The `exptime` argument has a resolution of `0.001` seconds. If `exptime` is `0`, then the item will never expire.
6600+
6601+
Example:
6602+
6603+
```lua
6604+
6605+
require "resty.core"
6606+
6607+
local cats = ngx.shared.cats
6608+
local succ, err = cats:set("Marry", "a nice cat", 0.1)
6609+
6610+
succ, err = cats:expire("Marry", 0.5)
6611+
6612+
ngx.sleep(0.2)
6613+
6614+
local val, err = cats:get("Marry")
6615+
ngx.say(val) -- "a nice cat"
6616+
```
6617+
6618+
This feature was first introduced in the `v0.10.11` release.
6619+
6620+
**Note:** This method requires the `resty.core.shdict` or `resty.core` modules from the [lua-resty-core](https://github.com/openresty/lua-resty-core) library.
6621+
6622+
See also [ngx.shared.DICT](#ngxshareddict).
6623+
6624+
[Back to TOC](#nginx-api-for-lua)
6625+
65466626
ngx.shared.DICT.flush_all
65476627
-------------------------
65486628
**syntax:** *ngx.shared.DICT:flush_all()*

‎doc/HttpLuaModule.wiki‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5196,6 +5196,8 @@ The resulting object <code>dict</code> has the following methods:
51965196
* [[#ngx.shared.DICT.lpop|lpop]]
51975197
* [[#ngx.shared.DICT.rpop|rpop]]
51985198
* [[#ngx.shared.DICT.llen|llen]]
5199+
* [[#ngx.shared.DICT.ttl|ttl]]
5200+
* [[#ngx.shared.DICT.expire|expire]]
51995201
* [[#ngx.shared.DICT.flush_all|flush_all]]
52005202
* [[#ngx.shared.DICT.flush_expired|flush_expired]]
52015203
* [[#ngx.shared.DICT.get_keys|get_keys]]
@@ -5491,6 +5493,74 @@ This feature was first introduced in the <code>v0.10.6</code> release.
54915493
54925494
See also [[#ngx.shared.DICT|ngx.shared.DICT]].
54935495
5496+
== ngx.shared.DICT.ttl ==
5497+
'''syntax:''' ''ttl, err = ngx.shared.DICT:ttl(key)''
5498+
5499+
'''context:''' ''init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, balancer_by_lua*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*''
5500+
5501+
'''requires:''' <code>resty.core.shdict</code> or <code>resty.core</code>
5502+
5503+
Retrieves the remaining TTL (time-to-live in seconds) of a key-value pair in the shm-based dictionary [[#ngx.shared.DICT|ngx.shared.DICT]]. Returns the TTL as a number if the operation is successfully completed or <code>nil</code> and an error message otherwise.
5504+
5505+
If the key does not exist (or has already expired), this method will return <code>nil</code> and the error string <code>"not found"</code>.
5506+
5507+
The TTL is originally determined by the <code>exptime</code> argument of the [[#ngx.shared.DICT.set|set]], [[#ngx.shared.DICT.add|add]], [[#ngx.shared.DICT.replace|replace]] (and the likes) methods. It has a time resolution of <code>0.001</code> seconds. A value of <code>0</code> means that the item will never expire.
5508+
5509+
Example:
5510+
5511+
<geshi lang="lua">
5512+
require "resty.core"
5513+
5514+
local cats = ngx.shared.cats
5515+
local succ, err = cats:set("Marry", "a nice cat", 0.5)
5516+
5517+
ngx.sleep(0.2)
5518+
5519+
local ttl, err = cats:ttl("Marry")
5520+
ngx.say(ttl) -- 0.3
5521+
</geshi>
5522+
5523+
This feature was first introduced in the <code>v0.10.11</code> release.
5524+
5525+
'''Note:''' This method requires the <code>resty.core.shdict</code> or <code>resty.core</code> modules from the [https://github.com/openresty/lua-resty-core lua-resty-core] library.
5526+
5527+
See also [[#ngx.shared.DICT|ngx.shared.DICT]].
5528+
5529+
== ngx.shared.DICT.expire ==
5530+
'''syntax:''' ''success, err = ngx.shared.DICT:expire(key, exptime)''
5531+
5532+
'''context:''' ''init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, balancer_by_lua*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*''
5533+
5534+
'''requires:''' <code>resty.core.shdict</code> or <code>resty.core</code>
5535+
5536+
Updates the <code>exptime</code> (in second) of a key-value pair in the shm-based dictionary [[#ngx.shared.DICT|ngx.shared.DICT]]. Returns a boolean indicating success if the operation completes or <code>nil</code> and an error message otherwise.
5537+
5538+
If the key does not exist, this method will return <code>nil</code> and the error string <code>"not found"</code>.
5539+
5540+
The <code>exptime</code> argument has a resolution of <code>0.001</code> seconds. If <code>exptime</code> is <code>0</code>, then the item will never expire.
5541+
5542+
Example:
5543+
5544+
<geshi lang="lua">
5545+
require "resty.core"
5546+
5547+
local cats = ngx.shared.cats
5548+
local succ, err = cats:set("Marry", "a nice cat", 0.1)
5549+
5550+
succ, err = cats:expire("Marry", 0.5)
5551+
5552+
ngx.sleep(0.2)
5553+
5554+
local val, err = cats:get("Marry")
5555+
ngx.say(val) -- "a nice cat"
5556+
</geshi>
5557+
5558+
This feature was first introduced in the <code>v0.10.11</code> release.
5559+
5560+
'''Note:''' This method requires the <code>resty.core.shdict</code> or <code>resty.core</code> modules from the [https://github.com/openresty/lua-resty-core lua-resty-core] library.
5561+
5562+
See also [[#ngx.shared.DICT|ngx.shared.DICT]].
5563+
54945564
== ngx.shared.DICT.flush_all ==
54955565
'''syntax:''' ''ngx.shared.DICT:flush_all()''
54965566

0 commit comments

Comments
 (0)