Cache::Memcached(3) User Contributed Perl Documentation Cache::Memcached(3)NAMECache::Memcached - client library for memcached (memory cache daemon)
SYNOPSIS
use Cache::Memcached;
$memd = new Cache::Memcached {
'servers' => [ "10.0.0.15:11211", "10.0.0.15:11212", "/var/sock/memcached",
"10.0.0.17:11211", [ "10.0.0.17:11211", 3 ] ],
'debug' => 0,
'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);
DESCRIPTION
This is the Perl API for memcached, a distributed memory cache daemon.
More information is available at:
http://www.danga.com/memcached/
CONSTRUCTOR
"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 allocates memory for
bucket distribution proportional to the total host weights.
Use "compress_threshold" to set a compression threshold, in bytes.
Values larger than this threshold will be compressed by "set" and
decompressed by "get".
Use "no_rehash" to disable finding a new memcached server when one
goes down. Your application may or may not need this, depending on
your expirations and key usage.
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.
Use "namespace" to prefix all keys with the provided namespace
value. That is, if you set namespace to "app1:" and later do a set
of "foo" to "bar", memcached is actually seeing you set "app1:foo"
to "bar".
The other useful key is "debug", which when set to true will
produce diagnostics on STDERR.
METHODS
"set_servers"
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_debug"
Sets the "debug" flag. See "new" constructor for more information.
"set_readonly"
Sets the "readonly" flag. See "new" constructor for more
information.
"set_norehash"
Sets the "no_rehash" 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.
"get"
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.
"set"
$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.
You may also use the alternate method name remove, so
Cache::Memcached looks like the Cache::Cache API.
"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.
"stats"
$memd->stats([$keys]);
Returns a hashref of statistical data regarding the memcache
server(s), the $memd object, or both. $keys can be an arrayref of
keys wanted, a single key wanted, or absent (in which case the
default value is malloc, sizes, self, and the empty string). These
keys are the values passed to the 'stats' command issued to the
memcached server(s), except for 'self' which is internal to the
$memd object. Allowed values are:
"misc"
The stats returned by a 'stats' command: pid, uptime, version,
bytes, get_hits, etc.
"malloc"
The stats returned by a 'stats malloc': total_alloc,
arena_size, etc.
"sizes"
The stats returned by a 'stats sizes'.
"self"
The stats for the $memd object itself (a copy of
$memd->{'stats'}).
"maps"
The stats returned by a 'stats maps'.
"cachedump"
The stats returned by a 'stats cachedump'.
"slabs"
The stats returned by a 'stats slabs'.
"items"
The stats returned by a 'stats items'.
"disconnect_all"
$memd->disconnect_all;
Closes all cached sockets to all memcached servers. You must do
this if your program forks and the parent has used this module at
all. Otherwise the children will try to use cached sockets and
they'll fight (as children do) and garble the client/server
protocol.
"flush_all"
$memd->flush_all;
Runs the memcached "flush_all" command on all configured hosts,
emptying all their caches. (or rather, invalidating all items in
the caches in an O(1) operation...) Running stats will still show
the item existing, they're just be non-existent and lazily
destroyed next time you try to detch any of them.
BUGS
When a server goes down, this module does detect it, and re-hashes the
request to the remaining servers, but the way it does it isn't very
clean. The result may be that it gives up during its rehashing and
refuses to get/set something it could've, had it been done right.
COPYRIGHT
This module is Copyright (c) 2003 Brad Fitzpatrick. 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.
WARRANTY
This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
FAQ
See the memcached website:
http://www.danga.com/memcached/
AUTHORS
Brad Fitzpatrick <brad@danga.com>
Anatoly Vorobey <mellon@pobox.com>
Brad Whitaker <whitaker@danga.com>
Jamie McCarthy <jamie@mccarthy.vg>
perl v5.14.0 2010-06-18 Cache::Memcached(3)
