=encoding utf-8 =head1 Name lua-resty-memcached - Lua memcached client driver for the ngx_lua based on the cosocket API This library is considered production ready. =head1 Description This Lua library is a memcached client driver for the ngx_lua nginx module: http://wiki.nginx.org/HttpLuaModule This Lua library takes advantage of ngx_lua's cosocket API, which ensures 100% nonblocking behavior. Note that at least L or L is required. =head1 Synopsis lua_package_path "/path/to/lua-resty-memcached/lib/?.lua;;"; server { location /test { content_by_lua ' local memcached = require "resty.memcached" local memc, err = memcached:new() if not memc then ngx.say("failed to instantiate memc: ", err) return end memc:set_timeout(1000) -- 1 sec -- or connect to a unix domain socket file listened -- by a memcached server: -- local ok, err = memc:connect("unix:/path/to/memc.sock") local ok, err = memc:connect("127.0.0.1", 11211) if not ok then ngx.say("failed to connect: ", err) return end local ok, err = memc:flush_all() if not ok then ngx.say("failed to flush all: ", err) return end local ok, err = memc:set("dog", 32) if not ok then ngx.say("failed to set dog: ", err) return end local res, flags, err = memc:get("dog") if err then ngx.say("failed to get dog: ", err) return end if not res then ngx.say("dog not found") return end ngx.say("dog: ", res) -- put it into the connection pool of size 100, -- with 10 seconds max idle timeout local ok, err = memc:set_keepalive(10000, 100) if not ok then ngx.say("cannot set keepalive: ", err) return end -- or just close the connection right away: -- local ok, err = memc:close() -- if not ok then -- ngx.say("failed to close: ", err) -- return -- end '; } } =head1 Methods The C argument provided in the following methods will be automatically escaped according to the URI escaping rules before sending to the memcached server. =head2 new C Creates a memcached object. In case of failures, returns C and a string describing the error. It accepts an optional C table argument. The following options are supported: =over =item * C an array table containing two functions for escaping and unescaping the memcached keys, respectively. By default, the memcached keys will be escaped and unescaped as URI components, that is =back memached:new{ key_transform = { ngx.escape_uri, ngx.unescape_uri } } =head2 connect C C Attempts to connect to the remote host and port that the memcached server is listening to or a local unix domain socket file listened by the memcached server. Before actually resolving the host name and connecting to the remote backend, this method will always look up the connection pool for matched idle connections created by previous calls of this method. =head2 set C Inserts an entry into memcached unconditionally. If the key already exists, overrides it. The C argument could also be a Lua table holding multiple Lua strings that are supposed to be concatenated as a whole (without any delimiters). For example, memc:set("dog", {"a ", {"kind of"}, " animal"}) is functionally equivalent to memc:set("dog", "a kind of animal") The C parameter is optional, defaults to C<0>. The C parameter is optional, defaults to C<0>. =head2 set_timeout C Sets the timeout (in ms) protection for subsequent operations, including the C method. Returns 1 when successful and nil plus a string describing the error otherwise. =head2 set_keepalive C Puts the current memcached connection immediately into the ngx_lua cosocket connection pool. You can specify the max idle timeout (in ms) when the connection is in the pool and the maximal size of the pool every nginx worker process. In case of success, returns C<1>. In case of errors, returns C with a string describing the error. Only call this method in the place you would have called the C method instead. Calling this method will immediately turn the current memcached object into the C state. Any subsequent operations other than C on the current objet will return the C error. =head2 get_reused_times C This method returns the (successfully) reused times for the current connection. In case of error, it returns C and a string describing the error. If the current connection does not come from the built-in connection pool, then this method always returns C<0>, that is, the connection has never been reused (yet). If the connection comes from the connection pool, then the return value is always non-zero. So this method can also be used to determine if the current connection comes from the pool. =head2 close C Closes the current memcached connection and returns the status. In case of success, returns C<1>. In case of errors, returns C with a string describing the error. =head2 add C Inserts an entry into memcached if and only if the key does not exist. The C argument could also be a Lua table holding multiple Lua strings that are supposed to be concatenated as a whole (without any delimiters). For example, memc:add("dog", {"a ", {"kind of"}, " animal"}) is functionally equivalent to memc:add("dog", "a kind of animal") The C parameter is optional, defaults to C<0>. The C parameter is optional, defaults to C<0>. In case of success, returns C<1>. In case of errors, returns C with a string describing the error. =head2 replace C Inserts an entry into memcached if and only if the key does exist. The C argument could also be a Lua table holding multiple Lua strings that are supposed to be concatenated as a whole (without any delimiters). For example, memc:replace("dog", {"a ", {"kind of"}, " animal"}) is functionally equivalent to memc:replace("dog", "a kind of animal") The C parameter is optional, defaults to C<0>. The C parameter is optional, defaults to C<0>. In case of success, returns C<1>. In case of errors, returns C with a string describing the error. =head2 append C Appends the value to an entry with the same key that already exists in memcached. The C argument could also be a Lua table holding multiple Lua strings that are supposed to be concatenated as a whole (without any delimiters). For example, memc:append("dog", {"a ", {"kind of"}, " animal"}) is functionally equivalent to memc:append("dog", "a kind of animal") The C parameter is optional, defaults to C<0>. The C parameter is optional, defaults to C<0>. In case of success, returns C<1>. In case of errors, returns C with a string describing the error. =head2 prepend C Prepends the value to an entry with the same key that already exists in memcached. The C argument could also be a Lua table holding multiple Lua strings that are supposed to be concatenated as a whole (without any delimiters). For example, memc:prepend("dog", {"a ", {"kind of"}, " animal"}) is functionally equivalent to memc:prepend("dog", "a kind of animal") The C parameter is optional, defaults to C<0>. The C parameter is optional, defaults to C<0>. In case of success, returns C<1>. In case of errors, returns C with a string describing the error. =head2 get C C Get a single entry or multiple entries in the memcached server via a single key or a talbe of keys. Let us first discuss the case When the key is a single string. The key's value and associated flags value will be returned if the entry is found and no error happens. In case of errors, C values will be turned for C and C and a 3rd (string) value will also be returned for describing the error. If the entry is not found, then three C values will be returned. Then let us discuss the case when the a Lua table of multiple keys are provided. In this case, a Lua table holding the key-result pairs will be always returned in case of success. Each value corresponding each key in the table is also a table holding two values, the key's value and the key's flags. If a key does not exist, then there is no responding entries in the C table. In case of errors, C will be returned, and the second return value will be a string describing the error. =head2 gets C C Just like the C method, but will also return the CAS unique value associated with the entry in addition to the key's value and flags. This method is usually used together with the C method. =head2 cas C Just like the C method but does a check and set operation, which means "store this data but only if no one else has updated since I last fetched it." The C argument can be obtained from the C method. =head2 touch C Update the expiration time of an existing key. Returns C<1> for success or C with a string describing the error otherwise. This method was first introduced in the C release. =head2 flush_all C Flushes (or invalidates) all the existing entries in the memcached server immediately (by default) or after the expiration specified by the C