NAME

       Cache::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".

           Use "connect_timeout" and "select_timeout" to set connection and polling timeouts. The
           "connect_timeout" defaults to .25 second, and the "select_timeout" defaults to 1
           second.

           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.

       "set_connect_timeout"
           Sets the connect timeout. See "new" constructor for more information.

       "set_select_timeout"
           Sets the select timeout. 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>