.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Cache::Memcached::libmemcached 3pm"
.TH Cache::Memcached::libmemcached 3pm "2022-12-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Cache::Memcached::libmemcached \- Cache interface to Memcached::libmemcached
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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", { \*(Aqcomplex\*(Aq => [ "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_... => ...,
\&      ...
\&  });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the Cache::Memcached compatible interface to libmemcached,
a C library to interface with memcached.
.PP
Cache::Memcached::libmemcached is built on top of Memcached::libmemcached.
While Memcached::libmemcached aims to port libmemcached \s-1API\s0 to perl, 
Cache::Memcached::libmemcached attempts to be \s-1API\s0 compatible with
Cache::Memcached, so it can be used as a drop-in replacement.
.PP
Cache::Memcached::libmemcached \fIinherits\fR 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 \s-1API\s0 therefore losing some of the portability in
case you want to replace it with some other package.
.SH "Cache::Memcached COMPATIBLE METHODS"
.IX Header "Cache::Memcached COMPATIBLE METHODS"
Except for the minor incompatibilities, below methods are compatible with
Cache::Memcached.
.SS "new"
.IX Subsection "new"
Takes one parameter, a hashref of options.
.PP
\fICache::Memcached options:\fR
.IX Subsection "Cache::Memcached options:"
.PP
\fIservers\fR
.IX Subsection "servers"
.PP
The value is passed to the \*(L"set_servers\*(R" method.
.PP
\fIcompress_threshold\fR
.IX Subsection "compress_threshold"
.PP
Set a compression threshold, in bytes. Values larger than this threshold will
be compressed by set and decompressed by get.
.PP
\fInamespace\fR
.IX Subsection "namespace"
.PP
The value is passed to the \*(L"namespace\*(R" method.
.PP
\fIdebug\fR
.IX Subsection "debug"
.PP
Sets the \f(CW\*(C`trace_level\*(C'\fR for the Memcached::libmemcached object.
.PP
\fIreadonly, no_rehash\fR
.IX Subsection "readonly, no_rehash"
.PP
These Cache::Memcached options are not supported.
.PP
\fIOptions specific to Cache::Memcached::libmemcached:\fR
.IX Subsection "Options specific to Cache::Memcached::libmemcached:"
.PP
\fIcompress_savings\fR
.IX Subsection "compress_savings"
.PP
\fIbehavior_*\fR
.IX Subsection "behavior_*"
.PP
Any of the \fImany\fR behaviors documented in
Memcached::libmemcached::memcached_behavior can be specified by using
argument key names that start with \f(CW\*(C`behavior_\*(C'\fR. For example:
.PP
.Vb 5
\&    behavior_ketama_weighted => 1,
\&    behavior_noreply => 1,
\&    behavior_number_of_replicas => 2,
\&    behavior_server_failure_limit => 3,
\&    behavior_auto_eject_hosts => 1,
.Ve
.PP
\fIno_block\fR
.IX Subsection "no_block"
.PP
\fIhashing_algorithm\fR
.IX Subsection "hashing_algorithm"
.PP
\fIdistribution_method\fR
.IX Subsection "distribution_method"
.PP
\fIbinary_protocol\fR
.IX Subsection "binary_protocol"
.PP
These are equivalent to the same options prefixed with \f(CW\*(C`behavior_\*(C'\fR.
.SS "set_servers"
.IX Subsection "set_servers"
.Vb 1
\&  $memd\->set_servers( [ \*(Aqserv1:port1\*(Aq, \*(Aqserv2:port2\*(Aq, ... ]);
.Ve
.PP
Calls \*(L"server_add\*(R" for each element of the supplied arrayref.
See \*(L"server_add\*(R" for details of valid values, including how to specify weights.
.SS "namespace"
.IX Subsection "namespace"
.Vb 2
\&  $memd\->namespace;
\&  $memd\->namespace($string);
.Ve
.PP
Without the argument return the current namespace prefix.  With the
argument set the namespace prefix to \fI\f(CI$string\fI\fR, and return the old prefix.
.PP
The effect is to pefix all keys with the provided namespace value. That is, if
you set namespace to \*(L"app1:\*(R" and later do a set of \*(L"foo\*(R" to \*(L"bar\*(R", memcached is
actually seeing you set \*(L"app1:foo\*(R" to \*(L"bar\*(R".
.PP
The namespace string must be less than 128 bytes (\s-1MEMCACHED_PREFIX_KEY_MAX_SIZE\s0).
.SS "get"
.IX Subsection "get"
.Vb 1
\&  my $val = $memd\->get($key);
.Ve
.PP
Retrieves a key from the memcached. Returns the value (automatically thawed
with Storable, if necessary) or undef.
.PP
Currently the arrayref form of \f(CW$key\fR is \s-1NOT\s0 supported. Perhaps in the future.
.SS "get_multi"
.IX Subsection "get_multi"
.Vb 1
\&  my $hashref = $memd\->get_multi(@keys);
.Ve
.PP
Retrieves multiple keys from the memcache doing just one query.
Returns a hashref of key/value pairs that were available.
.SS "set"
.IX Subsection "set"
.Vb 1
\&  $memd\->set($key, $value[, $expires]);
.Ve
.PP
Unconditionally sets a key to a given value in the memcache. Returns true if 
it was stored successfully.
.PP
Currently the arrayref form of \f(CW$key\fR is \s-1NOT\s0 supported. Perhaps in the future.
.SS "add"
.IX Subsection "add"
.Vb 1
\&  $memd\->add($key, $value[, $expires]);
.Ve
.PP
Like \fBset()\fR, but only stores in memcache if they key doesn't already exist.
.SS "replace"
.IX Subsection "replace"
.Vb 1
\&  $memd\->replace($key, $value[, $expires]);
.Ve
.PP
Like \fBset()\fR, but only stores in memcache if they key already exist.
.SS "append"
.IX Subsection "append"
.Vb 1
\&  $memd\->append($key, $value);
.Ve
.PP
Appends \f(CW$value\fR to whatever value associated with \f(CW$key\fR. Only available for
memcached > 1.2.4
.SS "prepend"
.IX Subsection "prepend"
.Vb 1
\&  $memd\->prepend($key, $value);
.Ve
.PP
Prepends \f(CW$value\fR to whatever value associated with \f(CW$key\fR. Only available for
memcached > 1.2.4
.SS "incr"
.IX Subsection "incr"
.SS "decr"
.IX Subsection "decr"
.Vb 2
\&  my $newval = $memd\->incr($key);
\&  my $newval = $memd\->decr($key);
\&
\&  my $newval = $memd\->incr($key, $offset);
\&  my $newval = $memd\->decr($key, $offset);
.Ve
.PP
Atomically increments or decrements the specified the integer value specified 
by \f(CW$key\fR. Returns undef if the key doesn't exist on the server.
.SS "delete"
.IX Subsection "delete"
.SS "remove"
.IX Subsection "remove"
.Vb 2
\&  $memd\->delete($key);
\&  $memd\->delete($key, $time);
.Ve
.PP
Deletes a key.
.PP
If \f(CW$time\fR 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 \*(L"get\*(R" command, but \*(L"add\*(R" and \*(L"replace\*(R" command
with this key will also fail (the \*(L"set\*(R" command will succeed, however). After
the time passes, the item is finally deleted from server memory.
.SS "flush_all"
.IX Subsection "flush_all"
.Vb 1
\&  $memd\->fush_all;
.Ve
.PP
Runs the memcached \*(L"flush_all\*(R" command on all configured hosts, emptying all 
their caches.
.SS "set_compress_threshold"
.IX Subsection "set_compress_threshold"
.Vb 1
\&  $memd\->set_compress_threshold($threshold);
.Ve
.PP
Set the compress threshold.
.SS "enable_compress"
.IX Subsection "enable_compress"
.Vb 1
\&  $memd\->enable_compress($bool);
.Ve
.PP
This is actually an alias to \fBset_compress_enable()\fR. The original version
from Cache::Memcached is, despite its naming, a setter as well.
.SS "stats"
.IX Subsection "stats"
.Vb 2
\&  my $h = $memd\->stats();
\&  my $h = $memd\->stats($keys);
.Ve
.PP
Returns a hashref of statistical data regarding the memcache server(s), the
\&\f(CW$memd\fR object, or both. \f(CW$keys\fR can be an arrayref of keys wanted, a single key
wanted, or absent (in which case the default value is \f(CW\*(C`[ \*(Aq\*(Aq ]\*(C'\fR). For each
key the \f(CW\*(C`stats\*(C'\fR command is run on each server.
.PP
For example \f(CW\*(C`<$memd\-\*(C'\fRstats([ '', 'sizes' ])>> would return a structure like
this:
.PP
.Vb 10
\&    {
\&        hosts => {
\&            \*(AqN.N.N.N:P\*(Aq => {
\&                misc => {
\&                    ...
\&                },
\&                sizes => {
\&                    ...
\&                },
\&            },
\&            ...,
\&        },
\&        totals => {
\&            ...
\&        }
\&    }
.Ve
.PP
The general stats (where the key is "") are returned with a key of \f(CW\*(C`misc\*(C'\fR.
The \f(CW\*(C`totals\*(C'\fR element contains the aggregate totals for all hosts of some of
the statistics.
.SS "disconnect_all"
.IX Subsection "disconnect_all"
Disconnects from servers
.SS "cas"
.IX Subsection "cas"
.Vb 1
\&  $memd\->cas($key, $cas, $value[, $exptime]);
.Ve
.PP
Overwrites data in the server as long as the \*(L"cas\*(R" value is still the same in
the server.
.PP
You can get the cas value of a result by calling \fBmemcached_result_cas()\fR on a
\&\fBmemcached_result_st\fR\|(3) structure.
.PP
Support for \*(L"cas\*(R" is disabled by default as there is a slight performance
penalty. To enable it use the \f(CW\*(C`support_cas\*(C'\fR option to \*(L"new\*(R".
.SH "Cache::Memcached::Fast COMPATIBLE METHODS"
.IX Header "Cache::Memcached::Fast COMPATIBLE METHODS"
.SS "server_versions"
.IX Subsection "server_versions"
.Vb 1
\&    $href = $memd\->server_versions;
.Ve
.PP
Returns a reference to hash, where \f(CW$href\fR\->{$server} holds corresponding server
version string, e.g. \*(L"1.4.4\*(R". \f(CW$server\fR is either host:port or /path/to/unix.sock.
.SH "Cache::Memcached::libmemcached SPECIFIC METHODS"
.IX Header "Cache::Memcached::libmemcached SPECIFIC METHODS"
These methods are libmemcached-specific.
.SS "server_add"
.IX Subsection "server_add"
.Vb 4
\&    $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 } );
.Ve
.PP
Adds a memcached server address with an optional weight (default 0).
.SH "UTILITY METHODS"
.IX Header "UTILITY METHODS"
\&\s-1WARNING:\s0 Please do not consider the existence for these methods to be final.
They may be renamed or may entirely disappear from future releases.
.SS "get_compress_threshold"
.IX Subsection "get_compress_threshold"
Return the current value of compress_threshold
.SS "set_compress_enable"
.IX Subsection "set_compress_enable"
Set the value of compress_enable
.SS "get_compress_enable"
.IX Subsection "get_compress_enable"
Return the current value of compress_enable
.SS "set_compress_savings"
.IX Subsection "set_compress_savings"
Set the value of compress_savings
.SS "get_compress_savings"
.IX Subsection "get_compress_savings"
Return the current value of compress_savings
.SH "BEHAVIOR CUSTOMIZATION"
.IX Header "BEHAVIOR CUSTOMIZATION"
Memcached::libmemcached supports \fImany\fR 'behaviors' that can be used to
configure the behavior of the library and its interaction with the servers.
.PP
Certain libmemcached behaviors can be configured with the following methods.
.PP
(\s-1NOTE:\s0 This \s-1API\s0 is not fixed yet)
.SS "set_no_block"
.IX Subsection "set_no_block"
.Vb 1
\&  $memd\->set_no_block( 1 );
.Ve
.PP
Set to use blocking/non\-blocking I/O. When this is in effect, \fBget()\fR becomes
flaky, so don't attempt to call it. This has the most effect for \fBset()\fR
operations, because libmemcached stops waiting for server response after
writing to the socket (\fBset()\fR will also always return success).
.PP
Please consult the man page for \f(CW\*(C`memcached_behavior_set()\*(C'\fR for details 
before setting.
.SS "is_no_block"
.IX Subsection "is_no_block"
Get the current value of no_block behavior.
.SS "set_distribution_method"
.IX Subsection "set_distribution_method"
.Vb 1
\&  $memd\->set_distribution_method( MEMCACHED_DISTRIBUTION_CONSISTENT );
.Ve
.PP
Set the distribution behavior.
.SS "get_distribution_method"
.IX Subsection "get_distribution_method"
Get the distribution behavior.
.SS "set_hashing_algorithm"
.IX Subsection "set_hashing_algorithm"
.Vb 1
\&  $memd\->set_hashing_algorithm( MEMCACHED_HASH_KETAMA );
.Ve
.PP
Set the hashing algorithm used.
.SS "get_hashing_algorithm"
.IX Subsection "get_hashing_algorithm"
Get the hashing algorithm used.
.SS "set_binary_protocol"
.IX Subsection "set_binary_protocol"
.SS "is_binary_protocol"
.IX Subsection "is_binary_protocol"
.Vb 2
\&  $memd\->set_binary_protocol( 1 );
\&  $binary = $memd\->is_binary_protocol();
.Ve
.PP
Use \f(CW\*(C`set_binary_protocol\*(C'\fR to enable/disable binary protocol.
Use \f(CW\*(C`is_binary_protocol\*(C'\fR to determine the current setting.
.SH "OPTIMIZE FLAG"
.IX Header "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 \s-1PERL_LIBMEMCACHED_OPTIMIZE\s0 to a true
value \fIbefore\fR loading the module.
.PP
This is an \s-1EXPERIMENTAL\s0 optimization and will possibly be replaced by
implementing the methods in C in Memcached::libmemcached.
.SH "VARIOUS MEMCACHED MODULES"
.IX Header "VARIOUS MEMCACHED MODULES"
Below are the various memcached modules available on \s-1CPAN.\s0
.PP
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)
.SS "Cache::Memcached"
.IX Subsection "Cache::Memcached"
This is the \*(L"original\*(R" module. It's mostly written in Perl, is slow, and lacks
significant features like support for the binary protocol.
.SS "Cache::Memcached::libmemcached"
.IX Subsection "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).
.SS "Cache::Memcached::Fast"
.IX Subsection "Cache::Memcached::Fast"
Cache::Memcached::Fast is a memcached client written in \s-1XS\s0 from scratch.
As of this writing benchmarks shows that Cache::Memcached::Fast is faster on 
\&\fBget_multi()\fR, and Cache::Memcached::libmemcached is faster on regular \fBget()\fR/\fBset()\fR.
Cache::Memcached::Fast doesn't support the binary protocol.
.SS "Memcached::libmemcached"
.IX Subsection "Memcached::libmemcached"
Memcached::libmemcached is a thin binding to the libmemcached C library
and provides access to most of the libmemcached \s-1API.\s0
.PP
If you don't care about a drop-in replacement for Cache::Memcached, and want to
benefit from the feature-rich efficient \s-1API\s0 that libmemcached offers, this is
the way to go.
.PP
Since the Memcached::libmemcached module is also the parent class of this module
you can call Memcached::libmemcached methods directly.
.SS "Cache::Memcached::XS"
.IX Subsection "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.
.SH "TODO"
.IX Header "TODO"
Check and improve compatibility with Cache::Memcached::Fast.
.PP
Add \fBforget_dead_hosts()\fR for greater Cache::Memcached compatibility?
.PP
Treat \s-1PERL_LIBMEMCACHED_OPTIMIZE\s0 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.
.PP
Redo tools/benchmarks.pl performance tests (ensuring that methods are not called in
void context unless it's appropriate).
.PP
Try using Cache::Memcached::Fast's test suite to test this module.
Via private lib/Cache/Memcached/libmemcachedAsFast.pm wrapper.
.PP
Implement automatic no-reply on calls in void context (like Cache::Memcached::Fast).
That should yield a signigicant performance boost.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 2008 Daisuke Maki <daisuke@endeworks.jp>
.PP
With contributions by Tim Bunce.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
See http://www.perl.com/perl/misc/Artistic.html