/ 
Cache-Memcached-Fast-0.03
River stage two • 31 direct dependents • 40 total dependents
/ Cache::Memcached::Fast

NAME

Cache::Memcached::Fast - Perl client for memcached, in C language

VERSION

Version 0.03

SYNOPSIS

use Cache::Memcached::Fast;

my $memd = new Cache::Memcached::Fast({
    servers => [ { address => 'localhost:11211', weight => 2.5 },
                 '192.168.254.2:11211',
                 { address => '/path/to/unix.sock' } ],
    namespace => 'my:',
    connect_timeout => 0.2,
    io_timeout => 0.5,
    close_on_error => 1,
    compress_threshold => 100_000,
    compress_ratio => 0.9,
    compress_algo => 'deflate',
    max_failures => 3,
    failure_timeout => 2,
    ketama_points => 150,
});

# Store scalars.
$memd->add('skey', 'text');
$memd->replace('skey', 'val');
$memd->set('nkey', 5);

# Store arbitrary Perl data structures.
my %hash = (a => 1, b => 2);
$memd->set('hash', \%hash);

# Add to strings.
$memd->prepend('skey', 'This is a ');
$memd->append('skey', 'ule.');

# Do arithmetic.
$memd->incr('nkey', 10);
print "OK\n" if $memd->decr('nkey', 3) == 12;

# Retrieve values.
my $val = $memd->get('skey');
print "OK\n" if $val eq 'This is a value.';
my $href = $memd->get_multi('hash', 'nkey');
print "OK\n" if $href->{hash}->{b} == 2 and $href->{nkey} == 12;

# Do atomic test-and-set operations.
my $cas_val = $memd->gets('nkey');
$$cas_val[1] = 0 if $$cas_val[1] == 12;
if ($memd->cas('nkey', @$cas_val)) {
    print "OK, value updated\n";
} else {
    print "Update failed, probably another client"
        . " has updated the value\n";
}

# Delete some data.
$memd->delete('skey');

# Wipe out all cached data.
$memd->flush_all;

DESCRIPTION

Cache::Memcahced::Fast is a Perl client for memcached, a memory cache daemon (http://www.danga.com/memcached/). Module core is implemented in C and tries hard to minimize number of system calls and to avoid any key/value copying for speed. As a result, it has very low CPU consumption.

API is largely compatible with Cache::Memcached, original pure Perl client, most users of the original module may start using this module by installing it and adding "::Fast" to the old name in their scripts (see "Compatibility with Cache::Memcached" below for full details).

CONSTRUCTOR

new
my $memd = new Cache::Memcached::Fast($params);

Create new client object. $params is a reference to a hash with client parameters. Currently recognized keys are:

servers
servers => [ { address => 'localhost:11211', weight => 2.5 },
             '192.168.254.2:11211',
             { address => '/path/to/unix.sock' } ],
(default: none)

The value is a reference to an array of server addresses. Each address is either a scalar, a hash reference, or an array reference (for compatibility with Cache::Memcached, deprecated). If hash reference, the keys are address (scalar) and weight (positive rational number). The server address is in the form host:port for network TCP connections, or /path/to/unix.sock for local Unix socket connections. When weight is not given, 1 is assumed. Client will distribute keys across servers proportionally to server weights.

If you want to get key distribution compatible with Cache::Memcached, all server weights should be integer, and their sum should be less than 32768.

namespace
namespace => 'my::'
(default: '')

The value is a scalar that will be prepended to all key names passed to the memcached server. By using different namespaces clients avoid interference with each other.

connect_timeout
connect_timeout => 0.7
(default: 0.25 seconds)

The value is a non-negative rational number of seconds to wait for connection to establish. Applies only to network connections. Zero disables timeout, but keep in mind that operating systems have their own heuristic connect timeout.

Note that network connect process consists of several steps: destination host address lookup, which may return several addresses in general case (especially for IPv6, see http://people.redhat.com/drepper/linux-rfc3484.html and http://people.redhat.com/drepper/userapi-ipv6.html), then the attempt to connect to one of those addresses. connect_timeout applies only to one such connect, i.e. to one connect(2) call. Thus overall connect process may take longer than connect_timeout seconds, but this is unavoidable.

io_timeout (or deprecated select_timeout)
io_timeout => 0.5
(default: 1.0 seconds)

The value is a non-negative rational number of seconds to wait before giving up on communicating with the server(s). Zero disables timeout.

Note that for commands that communicate with more than one server (like "get_multi") the timeout applies per server set, not per each server. Thus it won't expire if one server is quick enough to communicate, even if others are silent. But if some servers are dead those alive will finish communication, and then dead servers would timeout.

close_on_error
close_on_error => 0
(default: enabled)

The value is a boolean which enables (true) or disables (false) close_on_error mode. When enabled, any error response from the memcached server would make client close the connection. Note that such "error response" is different from "negative response". The latter means the server processed the command and yield negative result. The former means the server failed to process the command for some reason. close_on_error is enabled by default for safety. Consider the following scenario:

1 Client want to set some value, but mistakenly sends malformed command (this can't happen with current module of course ;)):
set key 10\r\n
value_data\r\n
2 Memcahced server reads first line, 'set key 10', and can't parse it, because there's wrong number of tokens in it. So it sends
ERROR\r\n
3 Then the server reads 'value_data' while it is in accept-command state! It can't parse it either (hopefully), and sends another
ERROR\r\n

But the client expects one reply per command, so after sending the next command it will think that the second 'ERROR' is a reply for this new command. This means that all replies would shift, including replies for "get" commands! By closing the connection we avoid such possibility.

When connection dies, or the client receives the reply that it can't understand, it closes the socket regardless the close_on_error setting.

compress_threshold
compress_threshold => 10_000
(default: -1)

The value is an integer. When positive it denotes the threshold size in bytes: data with the size equal or larger than this should be compressed. See "compress_ratio" and "compress_algo" below.

Negative value disables compression.

compress_ratio
compress_ratio => 0.9
(default: 0.8)

The value is a fractional number between 0 and 1. When "compress_threshold" triggers the compression, compressed size should be less or equal to (original-size * compress_ratio). Otherwise the data will be stored uncompressed.

compress_algo
compress_algo => 'bzip2'
(default: 'gzip')

The value is a scalar with the name of the compression algorithm (currently known are 'gzip', 'zip', 'bzip2', 'deflate', 'rawdeflate', 'lzop', 'lzf'). You have to have corresponding IO::Compress::<Algo> installed, otherwise the module will give a warning and compression will be disabled.

max_failures
max_failures => 3
(default: 0)

The value is a non-negative integer. When positive, if there happened max_failures in failure_timeout seconds, the client does not try to connect to this particular server for another failure_timeout seconds. Value of zero disables this behaviour.

failure_timeout
failure_timeout => 30
(default: 10 seconds)

The value is a positive integer number of seconds. See "max_failures".

ketama_points
ketama_points => 150
(default: 0)

The value is a non-negative integer. When positive, enables the Ketama consistent hashing algorithm (http://www.last.fm/user/RJ/journal/2007/04/10/392555/), and specifies the number of points the server with weight 1 will be mapped to. Thus each server will be mapped to ketama_points * weight points in continuum. Larger value will result in more uniform distribution. Note that the number of internal bin structures, and hence memory consumption, will be proportional to sum of such products. But bin structures themselves are small (two integers each), so you probably shouldn't worry.

Zero value disables the Ketama algorithm. See also server weight in "servers" above.

METHODS

enable_compress
$memd->enable_compress($enable);

Enable compression when boolean $enable is true, disable when false.

Note that you can enable compression only when you set "compress_threshold" to some positive value and "compress_algo" holds the name of a known compression algorithm.

Return: none.

set
$memd->set($key, $value);
$memd->set($key, $value, $expiration_time);

Store the $value on the server under the $key. $key should be a scalar. $value should be defined and may be of any Perl data type. When it is a reference, the referenced Perl data structure will be transparently serialized with Storable module.

Optional $expiration_time is a positive integer number of seconds after which the value will expire and wouldn't be accessible any longer.

Return: boolean, true if operation succeeded, false otherwise.

cas
$memd->cas($key, $cas, $value);
$memd->cas($key, $cas, $value, $expiration_time);

Store the $value on the server under the $key, but only if CAS (Consistent Access Storage) value associated with this key is equal to $cas. $cas is an opaque object returned with "gets" or "gets_multi".

See "set" for $key, $value, $expiration_time parameters description.

Return: boolean, true if operation succeeded, false otherwise.

This command first appears in memcached 1.2.4.

add
$memd->add($key, $value);
$memd->add($key, $value, $expiration_time);

Store the $value on the server under the $key, but only if the key doesn't exists on the server.

See "set" for $key, $value, $expiration_time parameters description.

Return: boolean, true if operation succeeded, false otherwise.

replace
$memd->replace($key, $value);
$memd->replace($key, $value, $expiration_time);

Store the $value on the server under the $key, but only if the key does exists on the server.

See "set" for $key, $value, $expiration_time parameters description.

Return: boolean, true if operation succeeded, false otherwise.

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

Append the $value to the current value on the server under the $key.

$key and $value should be scalars, as well as current value on the server. append doesn't affect expiration time of the value.

Return: boolean, true if operation succeeded, false otherwise.

This command first appears in memcached 1.2.4.

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

Prepend the $value to the current value on the server under the $key.

$key and $value should be scalars, as well as current value on the server. append doesn't affect expiration time of the value.

Return: boolean, true if operation succeeded, false otherwise.

This command first appears in memcached 1.2.4.

get
$memd->get($key);

Retrieve the value for a $key. $key should be a scalar.

Return: value associated with the $key, or nothing.

get_multi
$memd->get_multi(@keys);

Retrieve several values associated with @keys. @keys should be an array of scalars.

Return: reference to hash, where $href->{$key} holds corresponding value.

gets
$memd->gets($key);

Retrieve the value and its CAS for a $key. $key should be a scalar.

Return: reference to an array [$cas, $value], or nothing. You may conveniently pass it back to "cas" with @$res:

my $cas_val = $memd->gets($key);
# Update value.
if (defined $cas_val) {
    $$cas_val[1] = 3;
    $memd->cas($key, @$cas_val);
}

This command first appears in memcached 1.2.4.

gets_multi
$memd->gets_multi(@keys);

Retrieve several values and their CASs associated with @keys. @keys should be an array of scalars.

Return: reference to hash, where $href->{$key} holds a reference to an array [$cas, $value]. Compare with "gets".

This command first appears in memcached 1.2.4.

incr
$memd->incr($key);
$memd->incr($key, $increment);

Increment the value for the $key. If current value is not a number, zero is assumed. An optional $increment should be a positive integer, when not given 1 is assumed. Note that the server doesn't check for overflow.

Return: unsigned integer, new value for the $key, or nothing.

decr
$memd->decr($key);
$memd->decr($key, $decrement);

Decrement the value for the $key. If current value is not a number, zero is assumed. An optional $decrement should be a positive integer, when not given 1 is assumed. Note that the server does check for underflow, attempt to decrement the value below zero would set the value to zero.

Return: unsigned integer, new value for the $key, or nothing.

delete (or deprecated remove)
$memd->delete($key);
$memd->delete($key, $delay);

Delete $key and its value from the cache. $delay is an optional non-negative integer number of seconds to delay the operation. During this time "add" and "replace" commands will be rejected by the server. When omitted, zero is assumed, i.e. delete immediately.

Return: boolean, true if operation succeeded, false otherwise.

flush_all
$memd->flush_all;
$memd->flush_all($delay);

Flush all caches the client knows about. $delay is an optional non-negative integer number of seconds to delay the operation. The delay will be distributed across the servers. For instance, when you have three servers, and call flush_all(30), the servers would get 30, 15, 0 seconds delays respectively. When omitted, zero is assumed, i.e. flush immediately.

Return: boolean, true if operation succeeded, false otherwise.

Compatibility with Cache::Memcached

This module is designed to be a drop in replacement for Cache::Memcached. Where constructor parameters are the same as in Cache::Memcached, the default values are also the same, and new parameters are disabled by default (the exception is "close_on_error", which is absent in Cache::Memcached and enabled by default in this module). Internally Cache::Memcached::Fast uses the same hash function as Cache::Memcached, and thus should distribute the keys across several servers the same way. So both modules may be used interchangeably. Most users of the original module should be able to use this module after replacing "Cache::Memcached" with "Cache::Memcached::Fast", without further code modifications. However, as of this release, the following features of Cache::Memcached are not supported by Cache::Memcached::Fast (and some of them will never be):

Constructor parameters

no_rehash

Current implementation never rehashes keys, instead "max_failures" and "failure_timeout" are used.

readonly

Not supported. Easy to add. However I'm not sure about the demand for it, and it will slow down things a bit (because from design point of view it's better to add it on Perl side rather than on XS side).

debug

Not supported. Since the implementation is different, there can't be any compatibility on debug level.

Methods

Passing keys

Every key should be a scalar. The syntax when key is a reference to an array [$precomputed_hash, $key] is not supported.

set_servers

Not supported. Server set should not change after client object construction.

set_debug

Not supported. See "debug".

set_readonly

Not supported. See "readonly".

set_norehash

Not supported. See "no_rehash".

set_compress_threshold

Not supported. Easy to add. Currently you specify compress_threshold during client object construction.

stats

Not supported. Perhaps will appear in the future releases.

disconnect_all

Not supported. Easy to add. Meanwhile to disconnect from all servers you may do

undef $memd;

or

$memd = undef;

BUGS

Please report any bugs or feature requests to bug-cache-memcached-fast at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Cache-Memcached-Fast. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Cache::Memcached::Fast

You can also look for information at:

SEE ALSO

Cache::Memcached - original pure Perl memcached client.

http://www.danga.com/memcached/ - memcached website.

AUTHORS

Tomash Brechko, <tomash.brechko at gmail.com> - design and implementation.

Michael Monashev, <postmaster at softsearch.ru> - project management, design suggestions, testing.

ACKNOWLEDGEMENTS

Development of this module is sponsored by Monashev Co. Ltd.

WARRANTY

There's NONE, neither explicit nor implied. But you knew it already ;).

COPYRIGHT AND LICENSE

Copyright (C) 2007 Tomash Brechko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.