Cache::Memcached::Fast - Perl client for memcached, in C language
Version 0.05
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;
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).
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 => [ { 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 => '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 => 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 => 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 => 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:
set key 10\r\n value_data\r\n
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 => 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 => 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 => '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 => 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 => 30 (default: 10 seconds)
The value is a positive integer number of seconds. See "max_failures".
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.
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.
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.
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.
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.
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. prepend doesn't affect expiration time of the value.
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); }
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".
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.
delete
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.
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.
flush_all(30)
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):
Current implementation never rehashes keys, instead "max_failures" and "failure_timeout" are used.
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).
Not supported. Since the implementation is different, there can't be any compatibility on debug level.
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;
Current implementation does not preserve UTF-8 flag on scalars. Storing UTF-8 string and retrieving it back would return the same byte sequence, but UTF-8 flag will be forgotten. See utf8.
Likewise, tainted flag is neither tested nor preserved, storing tainted data and retrieving it back would clear tainted flag. See perlsec.
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.
bug-cache-memcached-fast at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Cache::Memcached::Fast
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Cache-Memcached-Fast
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Cache-Memcached-Fast
CPAN Ratings
http://cpanratings.perl.org/d/Cache-Memcached-Fast
Search CPAN
http://search.cpan.org/dist/Cache-Memcached-Fast
Cache::Memcached - original pure Perl memcached client.
http://www.danga.com/memcached/ - memcached website.
Tomash Brechko, <tomash.brechko at gmail.com> - design and implementation.
<tomash.brechko at gmail.com>
Michael Monashev, <postmaster at softsearch.ru> - project management, design suggestions, testing.
<postmaster at softsearch.ru>
Development of this module is sponsored by Monashev Co. Ltd.
There's NONE, neither explicit nor implied. But you knew it already ;).
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.
To install Cache::Memcached::Fast, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Cache::Memcached::Fast
CPAN shell
perl -MCPAN -e shell install Cache::Memcached::Fast
For more information on module installation, please visit the detailed CPAN module installation guide.