NAME

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

SYNOPSIS

    use Cache::Memcached::Fast;
  my $memd = Cache::Memcached::Fast->new({
      servers => [ { address => 'localhost:11211', weight => 2.5 },
                   '192.168.254.2:11211',
                   { address => '/path/to/unix.sock', noreply => 1 } ],
      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,
      hash_namespace => 1,
      serialize_methods => [ \&Storable::freeze, \&Storable::thaw ],
      utf8 => 1,
      max_size => 512 * 1024,
  });
  # 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->append_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->set_multi(map { [$_, 0] } @counters, 'c3', 'c4');
  $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);
  # Wait for all commands that were executed in nowait mode.
  $memd->nowait_push;
  # Wipe out all cached data.
  $memd->flush_all;

DESCRIPTION

Cache::Memcached::Fast is a Perl client for memcached, a memory cache daemon (<http://www.memcached.org>). 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 = Cache::Memcached::Fast->new($params);
    

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

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_methods" is set.

Return: none.

"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.

Return: scalar, the namespace prefix that was in effect before the call.

"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 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.

"set_multi"

  $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} holds the result value. See "set" to learn what the result value is.

"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" or "gats" or "gats_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", "gats", "cas" command sequence should be repeated.

cas command first appeared in memcached 1.2.4.

"cas_multi"

  $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} holds the result value. See "cas" to learn what the result value is.

cas command first appeared 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 for positive server reply, false for negative server reply, or undef in case of some error.

"add_multi"

  $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} holds the result value. See "add" to learn what the result value is.

"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 for positive server reply, false for negative server reply, or undef in case of some error.

"replace_multi"

  $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} holds the result value. See "replace" to learn what the result value is.

"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 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.

"append_multi"

  $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} holds the result value. See "append" to learn what the result value is.

append command first appeared 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. "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.

"prepend_multi"

  $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} holds the result value. See "prepend" to learn what the result value is.

prepend command first appeared 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);
  }
    

gets command first appeared 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".

gets command first appeared in memcached 1.2.4.

"incr"

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

Increment the value for the $key. Starting with memcached 1.3.3 $key should be set to a number or the command will fail. 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.

"incr_multi"

  $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} holds the result value. See "incr" to learn what the result value is.

"decr"

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

Decrement the value for the $key. Starting with memcached 1.3.3 $key should be set to a number or the command will fail. 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.

"decr_multi"

  $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} holds the result value. See "decr" to learn what the result value is.

"delete"

  $memd->delete($key);
    

Delete $key and its value from the cache.

Return: boolean, true for positive server reply, false for negative server reply, or undef in case of some error.

"remove" (deprecated)

Alias for "delete", for compatibility with Cache::Memcached.

"delete_multi"

  $memd->delete_multi(@keys);
    

Like "delete", but operates on more than one key. Takes the list of keys.

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} holds the result value. See "delete" to learn what the result value is.

"touch"

  $memd->touch($key, $expiration_time);
    

Update the expiration time of $key without fetching it.

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.

touch command first appeared in memcached 1.4.8.

"touch_multi"

  $memd->touch_multi(
      [$key],
      [$key, $expiration_time],
      ...
  );
    

Like "touch", but operates on more than one key. Takes the list of references to arrays each holding $key 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} holds the result value. See "touch" to learn what the result value is.

touch command first appeared in memcached 1.4.8.

"gat"

  $memd->gat($expiration_time, $key);
    

Update the expiration time and retrieve the value for a $key.

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

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

gat command first appeared in memcached 1.5.3.

"gat_multi"

  $memd->gat_multi($expiration_time, @keys);
    

Update the expiration time of the @keys and get the associated values. @keys should be an array of scalars.

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

gat command first appeared in memcached 1.5.3.

"gats"

  $memd->gats($expiration_time, $key);
    

Update the expiration time and Retrieve the value and its CAS for a $key.

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

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

gat command first appeared in memcached 1.5.3.

"gats_multi"

  $memd->gats_multi($expiration_time, @keys);
    

Update the expiration time and 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 "gats".

gat command first appeared in memcached 1.5.3.

"flush_all"

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

Flush all caches the client knows about. This command invalidates all items in the caches, none of them will be returned on subsequent retrieval command. $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.

"nowait_push"

  $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.

"server_versions"

  $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".

"disconnect_all"

  $memd->disconnect_all;
    

Closes all open sockets to memcached servers. Must be called after "fork" in perlfunc if the parent process has open sockets to memcacheds (as the child process inherits the socket and thus two processes end up using the same socket which leads to protocol errors.)

Return: nothing.

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, and "check_args", which see). 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):

Tainted data

In current implementation tainted flag is neither tested nor preserved, storing tainted data and retrieving it back would clear tainted flag. See perlsec.

Threads

This module is thread-safe when used with Perl >= 5.7.2. As with other Perl data each thread gets its own copy of Cache::Memcached::Fast object that is in scope when the thread is created. Such copies share no state, and may be used concurrently. For example:

  use threads;
  my $memd = Cache::Memcached::Fast->new({...});
  sub thread_job {
    $memd->set("key", "thread value");
  }
  threads->new(\&thread_job);
  $memd->set("key", "main value");

Here both "set"s will be executed concurrently, and the value of key will be either main value or thread value, depending on the timing of operations. Note that $memd inside "thread_job" internally refers to a different Cache::Memcached::Fast object than $memd from the outer scope. Each object has its own connections to servers, its own counter of outstanding replies for "nowait" mode, etc.

New object copy is created with the same constructor arguments, but initially is not connected to any server (even when master copy has open connections). No file descriptor is allocated until the command is executed through this new object.

You may safely create Cache::Memcached::Fast object from threads other than main thread, and/or pass them as parameters to threads::new(). However you can't return the object from top-level thread function. I.e., the following won't work:

  use threads;
  sub thread_job {
    return Cache::Memcached::Fast->new({...});
  }
  my $thread = threads->new(\&thread_job);
  my $memd = $thread->join;  # The object will be destroyed here.

This is a Perl limitation (see "BUGS AND LIMITATIONS" in threads).

SUPPORT

The code repository is available for public review and contribution at <https://github.com/JRaspass/Cache-Memcached-Fast>.

Please report any bugs or feature requests through the issue tracker at <https://github.com/JRaspass/Cache-Memcached-Fast/issues>.

SEE ALSO

• Cache::Memcached - original pure Perl memcached client.
• <https://memcached.org> - memcached website.

AUTHORS

• Tomash Brechko <tomash.brechko@gmail.com> - design and implementation.
• Michael Monashev <postmaster@softsearch.ru> - project management, design suggestions, testing.
• James Raspass <jraspass@gmail.com> - recent additions and current maintenance.

ACKNOWLEDGEMENTS

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

Thanks to Peter J. Holzer for enlightening on UTF-8 support.

Thanks to Yasuhiro Matsumoto for the initial Win32 patch.

COPYRIGHT AND LICENSE

Copyright © 2007-2010 Tomash Brechko. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.