.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Cache::Memcached::XS 3"
.TH Cache::Memcached::XS 3 "2006-07-02" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Cache::Memcached::XS \- client library for memcached (memory cache daemon) using libmemcache
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Cache::Memcached::XS;
.Ve
.PP
.Vb 8
\&  $memd = new Cache::Memcached {
\&    'servers' => [ "10.0.0.15:11211", "10.0.0.15:11212",
\&                   "10.0.0.17:11211", [ "10.0.0.17:11211", 3 ] ],
\&    'compress_threshold' => 10_000,
\&  };
\&  $memd->set_servers($array_ref);
\&  $memd->set_compress_threshold(10_000);
\&  $memd->enable_compress(0);
.Ve
.PP
.Vb 2
\&  $memd->set("my_key", "Some value");
\&  $memd->set("object_key", { 'complex' => [ "object", 2, 4 ]});
.Ve
.PP
.Vb 3
\&  $val = $memd->get("my_key");
\&  $val = $memd->get("object_key");
\&  if ($val) { print $val->{'complex'}->[2]; }
.Ve
.PP
.Vb 3
\&  $memd->incr("key");
\&  $memd->decr("key");
\&  $memd->incr("key", 2);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the Perl \s-1API\s0 for memcached, a distributed memory cache daemon.
More information is available at:
.PP
.Vb 1
\&  http://www.danga.com/memcached/
.Ve
.PP
This version differs from the original Cache::Memcached perl client in
that it uses the libmemcache library and uses quite a lot less \s-1CPU\s0.
.PP
A few features from the original client are not (yet) supported:
.IP "\- no_rehash" 4
.IX Item "- no_rehash"
.PD 0
.IP "\- debug" 4
.IX Item "- debug"
.IP "\- stats" 4
.IX Item "- stats"
.IP "\- disconnect_all" 4
.IX Item "- disconnect_all"
.PD
.PP
Other than this, it should be pretty much a drop-in replacement for the
original client.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .IP """new""" 4
.el .IP "\f(CWnew\fR" 4
.IX Item "new"
Takes one parameter, a hashref of options.  The most important key is
\&\f(CW\*(C`servers\*(C'\fR, but that can also be set later with the \f(CW\*(C`set_servers\*(C'\fR
method.  The servers must be an arrayref of hosts, each of which is
either a scalar of the form \f(CW\*(C`10.0.0.10:11211\*(C'\fR or an arrayref of the
former and an integer weight value.  (The default weight if
unspecified is 1.)  It's recommended that weight values be kept as low
as possible, as this module currently emulates weights by having
multiple identical servers.
.Sp
Use \f(CW\*(C`compress_threshold\*(C'\fR to set a compression threshold, in bytes.
Values larger than this threshold will be compressed by \f(CW\*(C`set\*(C'\fR and
decompressed by \f(CW\*(C`get\*(C'\fR.
.Sp
Use \f(CW\*(C`readonly\*(C'\fR to disable writes to backend memcached servers.  Only
get and get_multi will work.  This is useful in bizarre debug and
profiling cases only.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP """set_servers""" 4
.el .IP "\f(CWset_servers\fR" 4
.IX Item "set_servers"
Sets the server list this module distributes key gets and sets between.
The format is an arrayref of identical form as described in the \f(CW\*(C`new\*(C'\fR
constructor.
.ie n .IP """set_readonly""" 4
.el .IP "\f(CWset_readonly\fR" 4
.IX Item "set_readonly"
Sets the \f(CW\*(C`readonly\*(C'\fR flag.  See \f(CW\*(C`new\*(C'\fR constructor for more information.
.ie n .IP """set_compress_threshold""" 4
.el .IP "\f(CWset_compress_threshold\fR" 4
.IX Item "set_compress_threshold"
Sets the compression threshold. See \f(CW\*(C`new\*(C'\fR constructor for more information.
.ie n .IP """enable_compress""" 4
.el .IP "\f(CWenable_compress\fR" 4
.IX Item "enable_compress"
Temporarily enable or disable compression.  Has no effect if \f(CW\*(C`compress_threshold\*(C'\fR
isn't set, but has an overriding effect if it is.
.ie n .IP """get""" 4
.el .IP "\f(CWget\fR" 4
.IX Item "get"
my \f(CW$val\fR = \f(CW$memd\fR\->get($key);
.Sp
Retrieves a key from the memcache.  Returns the value (automatically
thawed with Storable, if necessary) or undef.
.Sp
The \f(CW$key\fR can optionally be an arrayref, with the first element being the
hash value, if you want to avoid making this module calculate a hash
value.  You may prefer, for example, to keep all of a given user's
objects on the same memcache server, so you could use the user's
unique id as the hash value.
.ie n .IP """get_multi""" 4
.el .IP "\f(CWget_multi\fR" 4
.IX Item "get_multi"
my \f(CW$hashref\fR = \f(CW$memd\fR\->get_multi(@keys);
.Sp
Retrieves multiple keys from the memcache doing just one query.
Returns a hashref of key/value pairs that were available.
.Sp
This method is recommended over regular 'get' as it lowers the number
of total packets flying around your network, reducing total latency,
since your app doesn't have to wait for each round-trip of 'get'
before sending the next one.
.ie n .IP """set""" 4
.el .IP "\f(CWset\fR" 4
.IX Item "set"
$memd\->set($key, \f(CW$value\fR[, \f(CW$exptime\fR]);
.Sp
Unconditionally sets a key to a given value in the memcache.  Returns true
if it was stored successfully.
.Sp
The \f(CW$key\fR can optionally be an arrayref, with the first element being the
hash value, as described above.
.Sp
The \f(CW$exptime\fR (expiration time) defaults to \*(L"never\*(R" if unspecified.  If
you want the key to expire in memcached, pass an integer \f(CW$exptime\fR.  If
value is less than 60*60*24*30 (30 days), time is assumed to be relative
from the present.  If larger, it's considered an absolute Unix time.
.ie n .IP """add""" 4
.el .IP "\f(CWadd\fR" 4
.IX Item "add"
$memd\->add($key, \f(CW$value\fR[, \f(CW$exptime\fR]);
.Sp
Like \f(CW\*(C`set\*(C'\fR, but only stores in memcache if the key doesn't already exist.
.ie n .IP """replace""" 4
.el .IP "\f(CWreplace\fR" 4
.IX Item "replace"
$memd\->replace($key, \f(CW$value\fR[, \f(CW$exptime\fR]);
.Sp
Like \f(CW\*(C`set\*(C'\fR, but only stores in memcache if the key already exists.  The
opposite of \f(CW\*(C`add\*(C'\fR.
.ie n .IP """delete""" 4
.el .IP "\f(CWdelete\fR" 4
.IX Item "delete"
$memd\->delete($key[, \f(CW$time\fR]);
.Sp
Deletes a key.  You may optionally provide an integer time value (in seconds) to
tell the memcached server to block new writes to this key for that many seconds.
(Sometimes useful as a hacky means to prevent races.)  Returns true if key
was found and deleted, and false otherwise.
.ie n .IP """incr""" 4
.el .IP "\f(CWincr\fR" 4
.IX Item "incr"
$memd\->incr($key[, \f(CW$value\fR]);
.Sp
Sends a command to the server to atomically increment the value for
\&\f(CW$key\fR by \f(CW$value\fR, or by 1 if \f(CW$value\fR is undefined.  Returns undef if \f(CW$key\fR
doesn't exist on server, otherwise it returns the new value after
incrementing.  Value should be zero or greater.  Overflow on server
is not checked.  Be aware of values approaching 2**32.  See decr.
.ie n .IP """decr""" 4
.el .IP "\f(CWdecr\fR" 4
.IX Item "decr"
$memd\->decr($key[, \f(CW$value\fR]);
.Sp
Like incr, but decrements.  Unlike incr, underflow is checked and new
values are capped at 0.  If server value is 1, a decrement of 2
returns 0, not \-1.
.SH "BUGS"
.IX Header "BUGS"
Any in libmemcache plus many others of my own.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module is Copyright (c) 2006 Jacques Caron & Oxado \s-1SARL\s0
All rights reserved.
.PP
You may distribute under the terms of either the \s-1GNU\s0 General Public
License or the Artistic License, as specified in the Perl \s-1README\s0 file.
.SH "WARRANTY"
.IX Header "WARRANTY"
This is free software. \s-1IT\s0 \s-1COMES\s0 \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0.
.SH "FAQ"
.IX Header "FAQ"
See the memcached website:
   http://www.danga.com/memcached/
.SH "AUTHORS"
.IX Header "AUTHORS"
Jacques Caron <jc@oxado.com>
.PP
Based on previous work by:
.PP
Brad Fitzpatrick <brad@danga.com>
.PP
Anatoly Vorobey <mellon@pobox.com>
.PP
Brad Whitaker <whitaker@danga.com>
.PP
Jamie McCarthy <jamie@mccarthy.vg>