Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

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 incompatiblities, 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 existance 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

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

To install Cache::Memcached::libmemcached, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Cache::Memcached::libmemcached

CPAN shell

perl -MCPAN -e shell
install Cache::Memcached::libmemcached

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Why not adopt me?

NAME

SYNOPSIS

DESCRIPTION

Cache::Memcached COMPATIBLE METHODS

new

Cache::Memcached options:

servers

compress_threshold

namespace

debug

readonly, no_rehash

Options specific to Cache::Memcached::libmemcached:

compress_savings

behavior_*

no_block

hashing_algorithm

distribution_method

binary_protocol

set_servers

namespace

get

get_multi

set

add

replace

append

prepend

incr

decr

delete

remove

flush_all

set_compress_threshold

enable_compress

stats

disconnect_all

cas

Cache::Memcached::Fast COMPATIBLE METHODS

server_versions

Cache::Memcached::libmemcached SPECIFIC METHODS

server_add

UTILITY METHODS

get_compress_threshold

set_compress_enable

get_compress_enable

set_compress_savings

get_compress_savings

BEHAVIOR CUSTOMIZATION

set_no_block

is_no_block

set_distribution_method

get_distribution_method

set_hashing_algorithm

get_hashing_algorithm

set_binary_protocol

is_binary_protocol

OPTIMIZE FLAG

VARIOUS MEMCACHED MODULES

Cache::Memcached

Cache::Memcached::libmemcached

Cache::Memcached::Fast

Memcached::libmemcached

Cache::Memcached::XS

TODO

AUTHOR

LICENSE

Module Install Instructions