Cache::Memcached::XS - client library for memcached (memory cache daemon) using libmemcache
use Cache::Memcached::XS; $memd = new Cache::Memcached { 'servers' => [ "10.0.0.15:11211", "10.0.0.15:11212", "10.0.0.17:11211", [ "10.0.0.17:11211", 3 ] ], 'compress_threshold' => 10_000, }; $memd->set_servers($array_ref); $memd->set_compress_threshold(10_000); $memd->enable_compress(0); $memd->set("my_key", "Some value"); $memd->set("object_key", { 'complex' => [ "object", 2, 4 ]}); $val = $memd->get("my_key"); $val = $memd->get("object_key"); if ($val) { print $val->{'complex'}->[2]; } $memd->incr("key"); $memd->decr("key"); $memd->incr("key", 2);
This is the Perl API for memcached, a distributed memory cache daemon. More information is available at:
http://www.danga.com/memcached/
This version differs from the original Cache::Memcached perl client in that it uses the libmemcache library and uses quite a lot less CPU.
A few features from the original client are not (yet) supported:
Other than this, it should be pretty much a drop-in replacement for the original client.
new
Takes one parameter, a hashref of options. The most important key is servers, but that can also be set later with the set_servers method. The servers must be an arrayref of hosts, each of which is either a scalar of the form 10.0.0.10:11211 or an arrayref of the former and an integer weight value. (The default weight if unspecified is 1.) It's recommended that weight values be kept as low as possible, as this module currently emulates weights by having multiple identical servers.
servers
set_servers
10.0.0.10:11211
Use compress_threshold to set a compression threshold, in bytes. Values larger than this threshold will be compressed by set and decompressed by get.
compress_threshold
set
get
Use readonly to disable writes to backend memcached servers. Only get and get_multi will work. This is useful in bizarre debug and profiling cases only.
readonly
Sets the server list this module distributes key gets and sets between. The format is an arrayref of identical form as described in the new constructor.
set_readonly
Sets the readonly flag. See new constructor for more information.
set_compress_threshold
Sets the compression threshold. See new constructor for more information.
enable_compress
Temporarily enable or disable compression. Has no effect if compress_threshold isn't set, but has an overriding effect if it is.
my $val = $memd->get($key);
Retrieves a key from the memcache. Returns the value (automatically thawed with Storable, if necessary) or undef.
The $key can optionally be an arrayref, with the first element being the hash value, if you want to avoid making this module calculate a hash value. You may prefer, for example, to keep all of a given user's objects on the same memcache server, so you could use the user's unique id as the hash value.
get_multi
my $hashref = $memd->get_multi(@keys);
Retrieves multiple keys from the memcache doing just one query. Returns a hashref of key/value pairs that were available.
This method is recommended over regular 'get' as it lowers the number of total packets flying around your network, reducing total latency, since your app doesn't have to wait for each round-trip of 'get' before sending the next one.
$memd->set($key, $value[, $exptime]);
Unconditionally sets a key to a given value in the memcache. Returns true if it was stored successfully.
The $key can optionally be an arrayref, with the first element being the hash value, as described above.
The $exptime (expiration time) defaults to "never" if unspecified. If you want the key to expire in memcached, pass an integer $exptime. If value is less than 60*60*24*30 (30 days), time is assumed to be relative from the present. If larger, it's considered an absolute Unix time.
add
$memd->add($key, $value[, $exptime]);
Like set, but only stores in memcache if the key doesn't already exist.
replace
$memd->replace($key, $value[, $exptime]);
Like set, but only stores in memcache if the key already exists. The opposite of add.
delete
$memd->delete($key[, $time]);
Deletes a key. You may optionally provide an integer time value (in seconds) to tell the memcached server to block new writes to this key for that many seconds. (Sometimes useful as a hacky means to prevent races.) Returns true if key was found and deleted, and false otherwise.
incr
$memd->incr($key[, $value]);
Sends a command to the server to atomically increment the value for $key by $value, or by 1 if $value is undefined. Returns undef if $key doesn't exist on server, otherwise it returns the new value after incrementing. Value should be zero or greater. Overflow on server is not checked. Be aware of values approaching 2**32. See decr.
decr
$memd->decr($key[, $value]);
Like incr, but decrements. Unlike incr, underflow is checked and new values are capped at 0. If server value is 1, a decrement of 2 returns 0, not -1.
Any in libmemcache plus many others of my own.
This module is Copyright (c) 2006 Jacques Caron & Oxado SARL All rights reserved.
You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.
This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
See the memcached website: http://www.danga.com/memcached/
Jacques Caron <jc@oxado.com>
Based on previous work by:
Brad Fitzpatrick <brad@danga.com>
Anatoly Vorobey <mellon@pobox.com>
Brad Whitaker <whitaker@danga.com>
Jamie McCarthy <jamie@mccarthy.vg>
To install Cache::Memcached::XS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Cache::Memcached::XS
CPAN shell
perl -MCPAN -e shell install Cache::Memcached::XS
For more information on module installation, please visit the detailed CPAN module installation guide.