Debian Codegraph @

README.markdown

raw
1 Name
2 ====
3
4 lua-resty-lrucache - Lua-land LRU cache based on the LuaJIT FFI.
5
6 Table of Contents
7 =================
8
9 * [Name](#name)
10 * [Status](#status)
11 * [Synopsis](#synopsis)
12 * [Description](#description)
13 * [Methods](#methods)
14 * [new](#new)
15 * [set](#set)
16 * [get](#get)
17 * [delete](#delete)
18 * [count](#count)
19 * [capacity](#capacity)
20 * [get_keys](#get_keys)
21 * [flush_all](#flush_all)
22 * [Prerequisites](#prerequisites)
23 * [Installation](#installation)
24 * [Community](#community)
25 * [English Mailing List](#english-mailing-list)
26 * [Chinese Mailing List](#chinese-mailing-list)
27 * [Bugs and Patches](#bugs-and-patches)
28 * [Author](#author)
29 * [Copyright and License](#copyright-and-license)
30 * [See Also](#see-also)
31
32 Status
33 ======
34
35 This library is considered production ready.
36
37 Synopsis
38 ========
39
40 ```lua
41 -- file myapp.lua: example "myapp" module
42
43 local _M = {}
44
45 -- alternatively: local lrucache = require "resty.lrucache.pureffi"
46 local lrucache = require "resty.lrucache"
47
48 -- we need to initialize the cache on the lua module level so that
49 -- it can be shared by all the requests served by each nginx worker process:
50 local c, err = lrucache.new(200) -- allow up to 200 items in the cache
51 if not c then
52 error("failed to create the cache: " .. (err or "unknown"))
53 end
54
55 function _M.go()
56 c:set("dog", 32)
57 c:set("cat", 56)
58 ngx.say("dog: ", c:get("dog"))
59 ngx.say("cat: ", c:get("cat"))
60
61 c:set("dog", { age = 10 }, 0.1) -- expire in 0.1 sec
62 c:delete("dog")
63
64 c:flush_all() -- flush all the cached data
65 end
66
67 return _M
68 ```
69
70 ```nginx
71 # nginx.conf
72
73 http {
74 # only if not using an official OpenResty release
75 lua_package_path "/path/to/lua-resty-lrucache/lib/?.lua;;";
76
77 server {
78 listen 8080;
79
80 location = /t {
81 content_by_lua_block {
82 require("myapp").go()
83 }
84 }
85 }
86 }
87 ```
88
89 Description
90 ===========
91
92 This library implements a simple LRU cache for
93 [OpenResty](https://openresty.org) and the
94 [ngx_lua](https://github.com/openresty/lua-nginx-module) module.
95
96 This cache also supports expiration time.
97
98 The LRU cache resides completely in the Lua VM and is subject to Lua GC. As
99 such, do not expect it to get shared across the OS process boundary. The upside
100 is that you can cache arbitrary complex Lua values (such as deep nested Lua
101 tables) without the overhead of serialization (as with `ngx_lua`'s [shared
102 dictionary
103 API](https://github.com/openresty/lua-nginx-module#lua_shared_dict)).
104 The downside is that your cache is always limited to the current OS process
105 (i.e. the current Nginx worker process). It does not really make much sense to
106 use this library in the context of
107 [init_by_lua](https://github.com/openresty/lua-nginx-module#lua_shared_dict)
108 because the cache will not get shared by any of the worker processes (unless
109 you just want to "warm up" the cache with predefined items which will get
110 inherited by the workers via `fork()`).
111
112 This library offers two different implementations in the form of two classes:
113 `resty.lrucache` and `resty.lrucache.pureffi`. Both implement the same API.
114 The only difference is that the latter is a pure FFI implementation that also
115 implements an FFI-based hash table for the cache lookup, while the former uses
116 native Lua tables.
117
118 If the cache hit rate is relatively high, you should use the `resty.lrucache`
119 class which is faster than `resty.lrucache.pureffi`.
120
121 However, if the cache hit rate is relatively low and there can be a *lot* of
122 variations of keys inserted into and removed from the cache, then you should
123 use the `resty.lrucache.pureffi` instead, because Lua tables are not good at
124 removing keys frequently. You would likely see the `resizetab` function call in
125 the LuaJIT runtime being very hot in [on-CPU flame
126 graphs](https://github.com/openresty/stapxx#lj-lua-stacks) if you use the
127 `resty.lrucache` class instead of `resty.lrucache.pureffi` in such a use case.
128
129 [Back to TOC](#table-of-contents)
130
131 Methods
132 =======
133
134 To load this library,
135
136 1. use an official [OpenResty release](https://openresty.org) or follow the
137 [Installation](#installation) instructions.
138 2. use `require` to load the library into a local Lua variable:
139
140 ```lua
141 local lrucache = require "resty.lrucache"
142 ```
143
144 or
145
146 ```lua
147 local lrucache = require "resty.lrucache.pureffi"
148 ```
149
150 [Back to TOC](#table-of-contents)
151
152 new
153 ---
154 `syntax: cache, err = lrucache.new(max_items [, load_factor])`
155
156 Creates a new cache instance. Upon failure, returns `nil` and a string
157 describing the error.
158
159 The `max_items` argument specifies the maximal number of items this cache can
160 hold.
161
162 The `load-factor` argument designates the "load factor" of the FFI-based
163 hash-table used internally by `resty.lrucache.pureffi`; the default value is
164 0.5 (i.e. 50%); if the load factor is specified, it will be clamped to the
165 range of `[0.1, 1]` (i.e. if load factor is greater than 1, it will be
166 saturated to 1; likewise, if load-factor is smaller than `0.1`, it will be
167 clamped to `0.1`). This argument is only meaningful for
168 `resty.lrucache.pureffi`.
169
170 [Back to TOC](#table-of-contents)
171
172 set
173 ---
174 `syntax: cache:set(key, value, ttl?, flags?)`
175
176 Sets a key with a value and an expiration time.
177
178 When the cache is full, the cache will automatically evict the least recently
179 used item.
180
181 The optional `ttl` argument specifies the expiration time. The time value is in
182 seconds, but you can also specify the fraction number part (e.g. `0.25`). A nil
183 `ttl` argument means the value would never expire (which is the default).
184
185 The optional `flags` argument specifies a user flags value associated with the
186 item to be stored. It can be retrieved later with the item. The user flags are
187 stored as an unsigned 32-bit integer internally, and thus must be specified as
188 a Lua number. If not specified, flags will have a default value of `0`. This
189 argument was added in the `v0.10` release.
190
191 [Back to TOC](#table-of-contents)
192
193 get
194 ---
195 `syntax: data, stale_data, flags = cache:get(key)`
196
197 Fetches a value with the key. If the key does not exist in the cache or has
198 already expired, `nil` will be returned.
199
200 Starting from `v0.03`, the stale data is also returned as the second return
201 value if available.
202
203 Starting from `v0.10`, the user flags value associated with the stored item is
204 also returned as the third return value. If no user flags were given to an
205 item, its default flags will be `0`.
206
207 [Back to TOC](#table-of-contents)
208
209 delete
210 ------
211 `syntax: cache:delete(key)`
212
213 Removes an item specified by the key from the cache.
214
215 [Back to TOC](#table-of-contents)
216
217 count
218 -----
219 `syntax: count = cache:count()`
220
221 Returns the number of items currently stored in the cache **including**
222 expired items if any.
223
224 The returned `count` value will always be greater or equal to 0 and smaller
225 than or equal to the `size` argument given to [`cache:new`](#new).
226
227 This method was added in the `v0.10` release.
228
229 [Back to TOC](#table-of-contents)
230
231 capacity
232 --------
233 `syntax: size = cache:capacity()`
234
235 Returns the maximum number of items the cache can hold. The return value is the
236 same as the `size` argument given to [`cache:new`](#new) when the cache was
237 created.
238
239 This method was added in the `v0.10` release.
240
241 [Back to TOC](#table-of-contents)
242
243 get_keys
244 --------
245 `syntax: keys = cache:get_keys(max_count?, res?)`
246
247 Fetch the list of keys currently inside the cache up to `max_count`. The keys
248 will be ordered in MRU fashion (Most-Recently-Used keys first).
249
250 This function returns a Lua (array) table (with integer keys) containing the
251 keys.
252
253 When `max_count` is `nil` or `0`, all keys (if any) will be returned.
254
255 When provided with a `res` table argument, this function will not allocate a
256 table and will instead insert the keys in `res`, along with a trailing `nil`
257 value.
258
259 This method was added in the `v0.10` release.
260
261 [Back to TOC](#table-of-contents)
262
263 flush_all
264 ---------
265 `syntax: cache:flush_all()`
266
267 Flushes all the existing data (if any) in the current cache instance. This is
268 an `O(1)` operation and should be much faster than creating a brand new cache
269 instance.
270
271 Note however that the `flush_all()` method of `resty.lrucache.pureffi` is an
272 `O(n)` operation.
273
274 [Back to TOC](#table-of-contents)
275
276 Prerequisites
277 =============
278
279 * [LuaJIT](http://luajit.org) 2.0+
280 * [ngx_lua](https://github.com/openresty/lua-nginx-module) 0.8.10+
281
282 [Back to TOC](#table-of-contents)
283
284 Installation
285 ============
286
287 It is recommended to use the latest [OpenResty release](https://openresty.org).
288 At least OpenResty 1.4.2.9 is required. Recent versions of OpenResty only
289 support LuaJIT, but if you are using an older version, make sure to enable
290 LuaJIT when building OpenResty by passing the `--with-luajit` option to its
291 `./configure` script. No extra Nginx configuration is required.
292
293 If you want to use this library with your own Nginx build (with ngx_lua), then
294 you need to ensure you are using ngx_lua 0.8.10 or greater.
295
296 By default, ngx_lua will search Lua files in /usr/local/share/lua/5.1/.
297 But `make install` will install this module to /usr/local/lib/lua.
298 So you may find the error like this:
299
300 ```text
301 nginx: [alert] failed to load the 'resty.lrucache' module
302 ```
303
304 You can install this module with the following command to resolve the above problem.
305
306 ```bash
307 cd lua-resty-lrucache
308 sudo make install LUA_LIB_DIR=/usr/local/share/lua/5.1
309 ```
310
311 You can also change the installation directory to any other directory you like with the LUA_LIB_DIR argument.
312
313 ```bash
314 cd lua-resty-lrucache
315 sudo make install LUA_LIB_DIR=/opt/nginx/lualib
316 ```
317
318 When not installed in /usr/local/share/lua/5.1, you also need to configure the
319 [lua_package_path](https://github.com/openresty/lua-nginx-module#lua_package_path)
320 directive to add the path to your lua-resty-lrucache source tree to ngx_lua's
321 Lua module search path, as in:
322
323 ```nginx
324 # nginx.conf
325
326 http {
327 lua_package_path "/opt/nginx/lualib/?.lua;;";
328 ...
329 }
330 ```
331
332 and then load the library in Lua:
333
334 ```lua
335 local lrucache = require "resty.lrucache"
336 ```
337
338 [Back to TOC](#table-of-contents)
339
340 Community
341 =========
342
343 [Back to TOC](#table-of-contents)
344
345 English Mailing List
346 --------------------
347
348 The [openresty-en](https://groups.google.com/group/openresty-en) mailing list
349 is for English speakers.
350
351 [Back to TOC](#table-of-contents)
352
353 Chinese Mailing List
354 --------------------
355
356 The [openresty](https://groups.google.com/group/openresty) mailing list is for
357 Chinese speakers.
358
359 [Back to TOC](#table-of-contents)
360
361 Bugs and Patches
362 ================
363
364 Please report bugs or submit patches by
365
366 1. creating a ticket on the [GitHub Issue
367 Tracker](https://github.com/openresty/lua-resty-lrucache/issues),
368 1. or posting to the [OpenResty community](#community).
369
370 [Back to TOC](#table-of-contents)
371
372 Author
373 ======
374
375 Yichun "agentzh" Zhang (章亦春) <[email protected]>, OpenResty Inc.
376
377 Shuxin Yang.
378
379 [Back to TOC](#table-of-contents)
380
381 Copyright and License
382 =====================
383
384 This module is licensed under the BSD license.
385
386 Copyright (C) 2014-2019, by Yichun "agentzh" Zhang, OpenResty Inc.
387
388 Copyright (C) 2014-2017, by Shuxin Yang.
389
390 All rights reserved.
391
392 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
393
394 * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
395
396 * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
397
398 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
399
400 [Back to TOC](#table-of-contents)
401
402 See Also
403 ========
404
405 * OpenResty: https://openresty.org
406 * the ngx_http_lua module: https://github.com/openresty/lua-nginx-module
407 * the ngx_stream_lua module: https://github.com/openresty/stream-lua-nginx-module
408 * the lua-resty-core library: https://github.com/openresty/lua-resty-core
409
410 [Back to TOC](#table-of-contents)