lua-libmemcached

An interface to the libmemcached C client for the Lua programming language.

Compatibile with libmemcached 1.0.3+ (except 1.0.12 and 1.0.14); exist requires 1.0.9+.

Installation

luarocks install --server=http://luarocks.org/dev lua-libmemcached LIBMEMCACHED_DIR=/opt/local

Usage

local libmemcached = require 'libmemcached'

new(options, encoder [, key_encode])

Creates a new instance of memcached client. The options string is used to configure server(s) connection and behavior; encoder - a table with two functions encode and decode; key_encode - a hash function for keys.

Example for cjson:

local encoder = require 'cjson'

Example for MessagePack:

local mp = require 'MessagePack'
local encoder = {encode = mp.pack, decode = mp.unpack}

Example for key encode:

local crypto = require 'crypto'

-- for text protocol
local key_encode = function(s)
    return crypto.digest('sha1', s)
end

-- for binary protocol
local key_encode = function(s)
    return crypto.digest('sha1', s, true)
end

Example using local server with binary protocol:

local c = libmemcached.new(
    '--server=127.0.0.1:11211 --binary-protocol',
    encoder, key_encode)

See more configuration options.

add(key, value[, expiration])

set(key, value[, expiration])

replace(key, value[, expiration])

Used to store information on the server. Keys are currently limited to 250 characters unless key_encode hash function is used; value can be of type string, number, boolean or table.

c:set('key', 'Hello World!', 100)

Returns true on success or nil if key was not found.

get(key)

Used to fetch a single value from the server.

c:get('key')

get_multi(keys)

Used to select multiple keys at once.

c:get_multi({'key', 'key2'})

append(key, value)

prepend(key, value)

Used to modify value by prepending or appending a string value to an existing one stored by memcached server.

delete(key)

Used to delete a key.

touch(key, expiration)

Used to update the expiration time on an existing key.

incr(key[, offset])

decr(key[, offset])

Increment or decrement keys (overflow and underflow are not detected), the value is then returned.

exist(key)

Check to see if a key exists.

flush([expiration])

Used to wipe clean the contents of memcached servers. It will either do this immediately or expire the content based on the expiration time passed.

get_behavior(flag)

set_behavior(flag, data)

The behavior used by the underlying libmemcached object. See more here.

c:set_behavior(libmemcached.behaviors.TCP_NODELAY, 1)

set_encoding_key(secret)

Sets the key used to encrypt and decrypt data (only AES is supported).

c:set_encoding_key('secret')

Caveats:

1. The binary protocol does not correctly handle encryption.
2. Segmentation fault with empty string value, e.g. c:set('x', '').

Setup

Install development dependencies:

make env
make lib test qa
eval "$(env/bin/luarocks path --bin)"