Партнёры:
Хостинг:
Cache::Memcached::Fast - Perl client for memcached, in C language
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_methods => [ \&IO::Compress::Gzip::gzip,
\&IO::Uncompress::Gunzip::gunzip ],
max_failures => 3,
failure_timeout => 2,
ketama_points => 150,
nowait => 1,
serialize_methods => [ \&Storable::freeze, \&Storable::thaw ],
utf8 => ($^V ge v5.8.1 ? 1 : 0),
});
# Get server versions.
my $versions = $memd->server_versions;
while (my ($server, $version) = each %$versions) {
#...
}
# Store scalars.
$memd->add('skey', 'text');
$memd->add_multi(['skey2', 'text2'], ['skey3', 'text3', 10]);
$memd->replace('skey', 'val');
$memd->replace_multi(['skey2', 'val2'], ['skey3', 'val3']);
$memd->set('nkey', 5);
$memd->set_multi(['nkey2', 10], ['skey3', 'text', 5]);
# Store arbitrary Perl data structures.
my %hash = (a => 1, b => 2);
my @list = (1, 2);
$memd->set('hash', \%hash);
$memd->set_multi(['scalar', 1], ['list', \@list]);
# Add to strings.
$memd->prepend('skey', 'This is a ');
$memd->prepend_multi(['skey2', 'This is a '], ['skey3', 'prefix ']);
$memd->append('skey', 'ue.');
$memd->prepend_multi(['skey2', 'ue.'], ['skey3', ' suffix']);
# Do arithmetic.
$memd->incr('nkey', 10);
print "OK\n" if $memd->decr('nkey', 3) == 12;
my @counters = qw(c1 c2); $memd->incr_multi(['c3', 2], @counters, ['c4', 10]);
# 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');
my @keys = qw(k1 k2 k3); $memd->delete_multi(@keys, ['k5', 20]);
# Wait for all commands that were executed in nowait mode. $memd->nowait_push;
# Wipe out all cached data. $memd->flush_all;
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.
nowait => 1 (default: disabled)
The value is a boolean which enables (true) or disables (false) nowait mode. If enabled, when you call a method that only returns its success status (like ``set''), in a void context, it sends the request to the server and returns immediately, not waiting the reply. This avoids the round-trip latency at a cost of uncertain command outcome.
Internally there is a counter of how many outstanding replies there should be, and on any command the client reads and discards any replies that have already arrived. When you later execute some method in a non-void context, all outstanding replies will be waited for, and then the reply for this command will be read and returned.
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
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 will shift, including replies for ``get'' commands! By closing the connection we eliminate 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_methods'' 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_methods => [ \&IO::Compress::Gzip::gzip,
\&IO::Uncompress::Gunzip::gunzip ]
(default: [ sub { ${$_[1]} = Compress::Zlib::memGzip(${$_[0]}) },
sub { ${$_[1]} = Compress::Zlib::memGunzip(${$_[0]}) } ]
when Compress::Zlib is available)
The value is a reference to an array holding two code references for compression and decompression routines respectively.
Compression routine is called when the size of the $value passed to ``set'' method family is greater than or equal to ``compress_threshold'' (also see ``compress_ratio''). The fact that compression was performed is remembered along with the data, and decompression routine is called on data retrieval with ``get'' method family. The interface of these routines should be the same as for IO::Compress family (for instance see IO::Compress::Gzip::gzip and IO::Uncompress::Gunzip::gunzip). I.e. compression routine takes a reference to scalar value and a reference to scalar where compressed result will be stored. Decompression routine takes a reference to scalar with compressed data and a reference to scalar where uncompressed result will be stored. Both routines should return true on success, and false on error.
By default we use Compress::Zlib because as of this writing it appears to be much faster than IO::Uncompress::Gunzip.
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 bucket structures, and hence memory consumption, will be proportional to sum of such products. But bucket 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.
serialize_methods => [ \&Storable::freeze, \&Storable::thaw ], (default: [ \&Storable::nfreeze, \&Storable::thaw ])
The value is a reference to an array holding two code references for serialization and deserialization routines respectively.
Serialization routine is called when the $value passed to ``set'' method family is a reference. The fact that serialization was performed is remembered along with the data, and deserialization routine is called on data retrieval with ``get'' method family. The interface of these routines should be the same as for Storable::nfreeze and Storable::thaw. I.e. serialization routine takes a reference and returns a scalar string; it should not fail. Deserialization routine takes scalar string and returns a reference; if deserialization fails (say, wrong data format) it should throw an exception (call die). The exception will be caught by the module and ``get'' will then pretend that the key hasn't been found.
utf8 => 1 (default: disabled)
The value is a boolean which enables (true) or disables (false) the conversion of Perl character strings to octet sequences in UTF-8 encoding on store, and the reverse conversion on fetch (when the retrieved data is marked as being UTF-8 octet sequence). See perlunicode.
check_args => 'skip' (default: not 'skip')
The value is a string. Currently the only recognized string is 'skip'.
By default all constructor parameter names are checked to be recognized, and a warning is given for unknown parameter. This will catch spelling errors that otherwise might go unnoticed.
When set to 'skip', the check will be bypassed. This may be desired when you share the same argument hash among different client versions, or among different clients.
$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_methods'' is set.
Return: none.
$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 by routines specified with ``serialize_methods'', which see.
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 for positive server reply, false for negative server reply, or undef in case of some error.
$memd->set_multi(
[$key, $value],
[$key, $value, $expiration_time],
...
);
Like ``set'', but operates on more than one key. Takes the list of references to arrays each holding $key, $value and optional $expiration_time.
Note that multi commands are not all-or-nothing, some operations may succeed, while others may fail.
Return: in list context returns the list of results, each $list[$index] is the result value corresponding to the argument at position $index. In scalar context, hash reference is returned, where $href->{$key} hols the result value. See ``set'' to learn what the result value is.
$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 for positive server reply, false for negative server reply, or undef in case of some error. Thus if the key exists on the server, false would mean that some other client has updated the value, and ``gets'', ``cas'' command sequence should be repeated.
cas command first appeared in memcached 1.2.4.
$memd->cas_multi(
[$key, $cas, $value],
[$key, $cas, $value, $expiration_time],
...
);
Like ``cas'', but operates on more than one key. Takes the list of references to arrays each holding $key, $cas, $value and optional $expiration_time.
Note that multi commands are not all-or-nothing, some operations may succeed, while others may fail.
Return: in list context returns the list of results, each $list[$index] is the result value corresponding to the argument at position $index. In scalar context, hash reference is returned, where $href->{$key} hols the result value. See ``cas'' to learn what the result value is.
cas command first appeared in memcached 1.2.4.
$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 for positive server reply, false for negative server reply, or undef in case of some error.
$memd->add_multi(
[$key, $value],
[$key, $value, $expiration_time],
...
);
Like ``add'', but operates on more than one key. Takes the list of references to arrays each holding $key, $value and optional $expiration_time.
Note that multi commands are not all-or-nothing, some operations may succeed, while others may fail.
Return: in list context returns the list of results, each $list[$index] is the result value corresponding to the argument at position $index. In scalar context, hash reference is returned, where $href->{$key} hols the result value. See ``add'' to learn what the result value is.
$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 for positive server reply, false for negative server reply, or undef in case of some error.
$memd->replace_multi(
[$key, $value],
[$key, $value, $expiration_time],
...
);
Like ``replace'', but operates on more than one key. Takes the list of references to arrays each holding $key, $value and optional $expiration_time.
Note that multi commands are not all-or-nothing, some operations may succeed, while others may fail.
Return: in list context returns the list of results, each $list[$index] is the result value corresponding to the argument at position $index. In scalar context, hash reference is returned, where $href->{$key} hols the result value. See ``replace'' to learn what the result value is.
$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 for positive server reply, false for negative server reply, or undef in case of some error.
append command first appeared in memcached 1.2.4.
$memd->append_multi(
[$key, $value],
...
);
Like ``append'', but operates on more than one key. Takes the list of references to arrays each holding $key, $value.
Note that multi commands are not all-or-nothing, some operations may succeed, while others may fail.
Return: in list context returns the list of results, each $list[$index] is the result value corresponding to the argument at position $index. In scalar context, hash reference is returned, where $href->{$key} hols the result value. See ``append'' to learn what the result value is.
append command first appeared in memcached 1.2.4.
$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.
Return: boolean, true for positive server reply, false for negative server reply, or undef in case of some error.
prepend command first appeared in memcached 1.2.4.
$memd->prepend_multi(
[$key, $value],
...
);
Like ``prepend'', but operates on more than one key. Takes the list of references to arrays each holding $key, $value.
Note that multi commands are not all-or-nothing, some operations may succeed, while others may fail.
Return: in list context returns the list of results, each $list[$index] is the result value corresponding to the argument at position $index. In scalar context, hash reference is returned, where $href->{$key} hols the result value. See ``prepend'' to learn what the result value is.
prepend command first appeared in memcached 1.2.4.
$memd->get($key);
Retrieve the value for a $key. $key should be a scalar.
Return: value associated with the $key, or nothing.
$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.
$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 command first appeared in memcached 1.2.4.
$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''.
gets command first appeared in memcached 1.2.4.
$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 false for negative server reply, or undef in case of some error.
$memd->incr_multi(
@keys,
[$key],
[$key, $increment],
...
);
Like ``incr'', but operates on more than one key. Takes the list of keys and references to arrays each holding $key and optional $increment.
Note that multi commands are not all-or-nothing, some operations may succeed, while others may fail.
Return: in list context returns the list of results, each $list[$index] is the result value corresponding to the argument at position $index. In scalar context, hash reference is returned, where $href->{$key} hols the result value. See ``incr'' to learn what the result value is.
$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. Similar to DBI, zero is returned as ``0E0'', and evaluates to true in a boolean context.
Return: unsigned integer, new value for the $key, or false for negative server reply, or undef in case of some error.
$memd->decr_multi(
@keys,
[$key],
[$key, $decrement],
...
);
Like ``decr'', but operates on more than one key. Takes the list of keys and references to arrays each holding $key and optional $decrement.
Note that multi commands are not all-or-nothing, some operations may succeed, while others may fail.
Return: in list context returns the list of results, each $list[$index] is the result value corresponding to the argument at position $index. In scalar context, hash reference is returned, where $href->{$key} hols the result value. See ``decr'' to learn what the result value is.
$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 for positive server reply, false for negative server reply, or undef in case of some error.
$memd->delete_multi(
@keys,
[$key],
[$key, $delay],
...
);
Like ``delete'', but operates on more than one key. Takes the list of keys and references to arrays each holding $key and optional $delay.
Note that multi commands are not all-or-nothing, some operations may succeed, while others may fail.
Return: in list context returns the list of results, each $list[$index] is the result value corresponding to the argument at position $index. In scalar context, hash reference is returned, where $href->{$key} hols the result value. See ``delete'' to learn what the result value is.
$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: reference to hash, where $href->{$server} holds corresponding result value. $server is either host:port or /path/to/unix.sock, as described in ``servers''. Result value is a boolean, true for positive server reply, false for negative server reply, or undef in case of some error.
$memd->nowait_push;
Push all pending requests to the server(s), and wait for all replies. When ``nowait'' mode is enabled, the requests issued in a void context may not reach the server(s) immediately (because the reply is not waited for). Instead they may stay in the send queue on the local host, or in the receive queue on the remote host(s), for quite a long time. This method ensures that they are delivered to the server(s), processed there, and the replies have arrived (or some error has happened that caused some connection(s) to be closed).
Destructor will call this method to ensure that all requests are processed before the connection is closed.
Return: nothing.
$memd->server_versions;
Get server versions.
Return: reference to hash, where $href->{$server} holds corresponding server version. $server is either host:port or /path/to/unix.sock, as described in ``servers''.
If the client would rehash the keys, a consistency problem would arise: when the failure occurs the client can't tell whether the server is down, or there's a (transient) network failure. While some clients might fail to reach a particular server, others may still reach it, so some clients will start rehashing, while others will not, and they will no longer agree which key goes where.
undef $memd;
or
$memd = undef;
perldoc Cache::Memcached::Fast
You can also look for information at:
Cache::Memcached - original pure Perl memcached client.
<http://www.danga.com/memcached/> - memcached website.
Michael Monashev, "<postmaster at softsearch.ru>" - project management, design suggestions, testing.
Thanks to Peter J. Holzer for enlightening on UTF-8 support.
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.
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |