Provided by: libcache-memcached-libmemcached-perl_0.04001-1_all bug

NAME

       Cache::Memcached::libmemcached - Cache interface to Memcached::libmemcached

SYNOPSIS

         use Cache::Memcached::libmemcached;

         my $memd = Cache::Memcached::libmemcached->new({
             servers => [
                   "10.0.0.15:11211",
                   [ "10.0.0.15:11212", 2 ], # weight
                   "/var/sock/memcached"
             ],
             compress_threshold => 10_000,
             # ... many more options supported
         });

         $memd->set("my_key", "Some value");
         $memd->set("object_key", { 'complex' => [ "object", 2, 4 ]});

         $val = $memd->get("my_key");
         $val = $memd->get("object_key");
         print $val->{complex}->[2] if $val;

         $memd->incr("key");
         $memd->decr("key");
         $memd->incr("key", 2);

         $memd->delete("key");
         $memd->remove("key"); # Alias to delete

         my $hashref = $memd->get_multi(@keys);

         # Import Memcached::libmemcached constants - explicitly by name or by tags
         # see Memcached::libmemcached::constants for a list
         use Cache::Memcached::libmemcached qw(MEMCACHED_DISTRIBUTION_CONSISTENT);
         use Cache::Memcached::libmemcached qw(
             :defines
             :memcached_allocated
             :memcached_behavior
             :memcached_callback
             :memcached_connection
             :memcached_hash
             :memcached_return
             :memcached_server_distribution
         );

         my $memd = Cache::Memcached::libmemcached->new({
             distribution_method => MEMCACHED_DISTRIBUTION_CONSISTENT,
             hashing_algorithm   => MEMCACHED_HASH_FNV1A_32,
             behavior_... => ...,
             ...
         });

DESCRIPTION

       This is the Cache::Memcached compatible interface to libmemcached, a C library to
       interface with memcached.

       Cache::Memcached::libmemcached is built on top of Memcached::libmemcached.  While
       Memcached::libmemcached aims to port libmemcached API to perl,
       Cache::Memcached::libmemcached attempts to be API compatible with Cache::Memcached, so it
       can be used as a drop-in replacement.

       Cache::Memcached::libmemcached inherits from Memcached::libmemcached.  While you are free
       to use the Memcached::libmemcached specific methods directly on the object, doing so will
       mean that your code is no longer compatible with the original Cache::Memcached API
       therefore losing some of the portability in case you want to replace it with some other
       package.

Cache::Memcached COMPATIBLE METHODS

       Except for the minor incompatibilities, below methods are compatible with
       Cache::Memcached.

   new
       Takes one parameter, a hashref of options.

       Cache::Memcached options:

       servers

       The value is passed to the "set_servers" method.

       compress_threshold

       Set a compression threshold, in bytes. Values larger than this threshold will be
       compressed by set and decompressed by get.

       namespace

       The value is passed to the "namespace" method.

       debug

       Sets the "trace_level" for the Memcached::libmemcached object.

       readonly, no_rehash

       These Cache::Memcached options are not supported.

       Options specific to Cache::Memcached::libmemcached:

       compress_savings

       behavior_*

       Any of the many behaviors documented in Memcached::libmemcached::memcached_behavior can be
       specified by using argument key names that start with "behavior_". For example:

           behavior_ketama_weighted => 1,
           behavior_noreply => 1,
           behavior_number_of_replicas => 2,
           behavior_server_failure_limit => 3,
           behavior_auto_eject_hosts => 1,

       no_block

       hashing_algorithm

       distribution_method

       binary_protocol

       These are equivalent to the same options prefixed with "behavior_".

   set_servers
         $memd->set_servers( [ 'serv1:port1', 'serv2:port2', ... ]);

       Calls "server_add" for each element of the supplied arrayref.  See "server_add" for
       details of valid values, including how to specify weights.

   namespace
         $memd->namespace;
         $memd->namespace($string);

       Without the argument return the current namespace prefix.  With the argument set the
       namespace prefix to $string, and return the old prefix.

       The effect is to pefix 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 namespace string must be less than 128 bytes (MEMCACHED_PREFIX_KEY_MAX_SIZE).

   get
         my $val = $memd->get($key);

       Retrieves a key from the memcached. Returns the value (automatically thawed with Storable,
       if necessary) or undef.

       Currently the arrayref form of $key is NOT supported. Perhaps in the future.

   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.

   set
         $memd->set($key, $value[, $expires]);

       Unconditionally sets a key to a given value in the memcache. Returns true if it was stored
       successfully.

       Currently the arrayref form of $key is NOT supported. Perhaps in the future.

   add
         $memd->add($key, $value[, $expires]);

       Like set(), but only stores in memcache if they key doesn't already exist.

   replace
         $memd->replace($key, $value[, $expires]);

       Like set(), but only stores in memcache if they key already exist.

   append
         $memd->append($key, $value);

       Appends $value to whatever value associated with $key. Only available for memcached >
       1.2.4

   prepend
         $memd->prepend($key, $value);

       Prepends $value to whatever value associated with $key. Only available for memcached >
       1.2.4

   incr
   decr
         my $newval = $memd->incr($key);
         my $newval = $memd->decr($key);

         my $newval = $memd->incr($key, $offset);
         my $newval = $memd->decr($key, $offset);

       Atomically increments or decrements the specified the integer value specified by $key.
       Returns undef if the key doesn't exist on the server.

   delete
   remove
         $memd->delete($key);
         $memd->delete($key, $time);

       Deletes a key.

       If $time is non-zero then the item is marked for later expiration. Expiration works by
       placing the item into a delete queue, which means that it won't possible to retrieve it by
       the "get" command, but "add" and "replace" command with this key will also fail (the "set"
       command will succeed, however). After the time passes, the item is finally deleted from
       server memory.

   flush_all
         $memd->fush_all;

       Runs the memcached "flush_all" command on all configured hosts, emptying all their caches.

   set_compress_threshold
         $memd->set_compress_threshold($threshold);

       Set the compress threshold.

   enable_compress
         $memd->enable_compress($bool);

       This is actually an alias to set_compress_enable(). The original version from
       Cache::Memcached is, despite its naming, a setter as well.

   stats
         my $h = $memd->stats();
         my $h = $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 "[ '' ]"). For each key the "stats" command is run on each
       server.

       For example "<$memd-"stats([ '', 'sizes' ])>> would return a structure like this:

           {
               hosts => {
                   'N.N.N.N:P' => {
                       misc => {
                           ...
                       },
                       sizes => {
                           ...
                       },
                   },
                   ...,
               },
               totals => {
                   ...
               }
           }

       The general stats (where the key is "") are returned with a key of "misc".  The "totals"
       element contains the aggregate totals for all hosts of some of the statistics.

   disconnect_all
       Disconnects from servers

   cas
         $memd->cas($key, $cas, $value[, $exptime]);

       Overwrites data in the server as long as the "cas" value is still the same in the server.

       You can get the cas value of a result by calling memcached_result_cas() on a
       memcached_result_st(3) structure.

       Support for "cas" is disabled by default as there is a slight performance penalty. To
       enable it use the "support_cas" option to "new".

Cache::Memcached::Fast COMPATIBLE METHODS

   server_versions
           $href = $memd->server_versions;

       Returns a reference to hash, where $href->{$server} holds corresponding server version
       string, e.g. "1.4.4". $server is either host:port or /path/to/unix.sock.

Cache::Memcached::libmemcached SPECIFIC METHODS

       These methods are libmemcached-specific.

   server_add
           $self->server_add( $server_host_port );   # 10.10.10.10:11211
           $self->server_add( $server_socket_path ); # /path/to/socket
           $self->server_add( [ $server, $weight ] );
           $self->server_add( { address => $server, weight => $weight } );

       Adds a memcached server address with an optional weight (default 0).

UTILITY METHODS

       WARNING: Please do not consider the existence for these methods to be final.  They may be
       renamed or may entirely disappear from future releases.

   get_compress_threshold
       Return the current value of compress_threshold

   set_compress_enable
       Set the value of compress_enable

   get_compress_enable
       Return the current value of compress_enable

   set_compress_savings
       Set the value of compress_savings

   get_compress_savings
       Return the current value of compress_savings

BEHAVIOR CUSTOMIZATION

       Memcached::libmemcached supports many 'behaviors' that can be used to configure the
       behavior of the library and its interaction with the servers.

       Certain libmemcached behaviors can be configured with the following methods.

       (NOTE: This API is not fixed yet)

   set_no_block
         $memd->set_no_block( 1 );

       Set to use blocking/non-blocking I/O. When this is in effect, get() becomes flaky, so
       don't attempt to call it. This has the most effect for set() operations, because
       libmemcached stops waiting for server response after writing to the socket (set() will
       also always return success).

       Please consult the man page for "memcached_behavior_set()" for details before setting.

   is_no_block
       Get the current value of no_block behavior.

   set_distribution_method
         $memd->set_distribution_method( MEMCACHED_DISTRIBUTION_CONSISTENT );

       Set the distribution behavior.

   get_distribution_method
       Get the distribution behavior.

   set_hashing_algorithm
         $memd->set_hashing_algorithm( MEMCACHED_HASH_KETAMA );

       Set the hashing algorithm used.

   get_hashing_algorithm
       Get the hashing algorithm used.

   set_binary_protocol
   is_binary_protocol
         $memd->set_binary_protocol( 1 );
         $binary = $memd->is_binary_protocol();

       Use "set_binary_protocol" to enable/disable binary protocol.  Use "is_binary_protocol" to
       determine the current setting.

OPTIMIZE FLAG

       If you are 100% sure that you won't be using the master key support (where you provide an
       arrayref as the key) you can get about 4~5% performance boost by setting the environment
       variable named PERL_LIBMEMCACHED_OPTIMIZE to a true value before loading the module.

       This is an EXPERIMENTAL optimization and will possibly be replaced by implementing the
       methods in C in Memcached::libmemcached.

VARIOUS MEMCACHED MODULES

       Below are the various memcached modules available on CPAN.

       Please check tool/benchmark.pl for a live comparison of these modules.  (except for
       Cache::Memcached::XS, which I wasn't able to compile under my main dev environment)

   Cache::Memcached
       This is the "original" module. It's mostly written in Perl, is slow, and lacks significant
       features like support for the binary protocol.

   Cache::Memcached::libmemcached
       Cache::Memcached::libmemcached, this module, is a perl binding for libmemcached
       (http://tangent.org/552/libmemcached.html).  Not to be confused with libmemcache (see
       below).

   Cache::Memcached::Fast
       Cache::Memcached::Fast is a memcached client written in XS from scratch.  As of this
       writing benchmarks shows that Cache::Memcached::Fast is faster on get_multi(), and
       Cache::Memcached::libmemcached is faster on regular get()/set().  Cache::Memcached::Fast
       doesn't support the binary protocol.

   Memcached::libmemcached
       Memcached::libmemcached is a thin binding to the libmemcached C library and provides
       access to most of the libmemcached API.

       If you don't care about a drop-in replacement for Cache::Memcached, and want to benefit
       from the feature-rich efficient API that libmemcached offers, this is the way to go.

       Since the Memcached::libmemcached module is also the parent class of this module you can
       call Memcached::libmemcached methods directly.

   Cache::Memcached::XS
       Cache::Memcached::XS is a binding for libmemcache
       (http://people.freebsd.org/~seanc/libmemcache/).  The main memcached site at
       http://danga.com/memcached/apis.bml seems to indicate that the underlying libmemcache is
       no longer in active development.  The module hasn't been updated since 2006.

TODO

       Check and improve compatibility with Cache::Memcached::Fast.

       Add forget_dead_hosts() for greater Cache::Memcached compatibility?

       Treat PERL_LIBMEMCACHED_OPTIMIZE as the default and add a subclass that handles the
       arrayref master key concept. Then the custom methods (get set add replace prepend append
       cas delete) can then all be removed and the libmemcached ones used directly.
       Alternatively, add master key via array ref support to the methods in ::libmemcached.
       Either way the effect on performance should be significant.

       Redo tools/benchmarks.pl performance tests (ensuring that methods are not called in void
       context unless it's appropriate).

       Try using Cache::Memcached::Fast's test suite to test this module.  Via private
       lib/Cache/Memcached/libmemcachedAsFast.pm wrapper.

       Implement automatic no-reply on calls in void context (like Cache::Memcached::Fast).  That
       should yield a signigicant performance boost.

AUTHOR

       Copyright (c) 2008 Daisuke Maki <daisuke@endeworks.jp>

       With contributions by Tim Bunce.

LICENSE

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       See http://www.perl.com/perl/misc/Artistic.html