File Coverage

blib/lib/Cache/Memcached/Fast.pm
Criterion Covered Total %
statement 46 66 69.7
branch 17 24 70.8
condition 12 20 60.0
subroutine 8 11 72.7
pod 1 1 100.0
total 84 122 68.8


line stmt bran cond sub pod time code
1             # See the end of the file for copyright and license.
2             #
3              
4             package Cache::Memcached::Fast;
5              
6 17     17   962520 use 5.006;
  17         199  
7 17     17   78 use strict;
  17         28  
  17         335  
8 17     17   70 use warnings;
  17         37  
  17         972  
9              
10              
11             =head1 NAME
12              
13             Cache::Memcached::Fast - Perl client for B, in C language
14              
15             =head1 VERSION
16              
17             Version 0.26.
18              
19             =cut
20              
21             our $VERSION = '0.26';
22              
23              
24             =head1 SYNOPSIS
25              
26             use Cache::Memcached::Fast;
27              
28             my $memd = new Cache::Memcached::Fast({
29             servers => [ { address => 'localhost:11211', weight => 2.5 },
30             '192.168.254.2:11211',
31             { address => '/path/to/unix.sock', noreply => 1 } ],
32             namespace => 'my:',
33             connect_timeout => 0.2,
34             io_timeout => 0.5,
35             close_on_error => 1,
36             compress_threshold => 100_000,
37             compress_ratio => 0.9,
38             compress_methods => [ \&IO::Compress::Gzip::gzip,
39             \&IO::Uncompress::Gunzip::gunzip ],
40             max_failures => 3,
41             failure_timeout => 2,
42             ketama_points => 150,
43             nowait => 1,
44             hash_namespace => 1,
45             serialize_methods => [ \&Storable::freeze, \&Storable::thaw ],
46             utf8 => ($^V ge v5.8.1 ? 1 : 0),
47             max_size => 512 * 1024,
48             });
49              
50             # Get server versions.
51             my $versions = $memd->server_versions;
52             while (my ($server, $version) = each %$versions) {
53             #...
54             }
55              
56             # Store scalars.
57             $memd->add('skey', 'text');
58             $memd->add_multi(['skey2', 'text2'], ['skey3', 'text3', 10]);
59              
60             $memd->replace('skey', 'val');
61             $memd->replace_multi(['skey2', 'val2'], ['skey3', 'val3']);
62              
63             $memd->set('nkey', 5);
64             $memd->set_multi(['nkey2', 10], ['skey3', 'text', 5]);
65              
66             # Store arbitrary Perl data structures.
67             my %hash = (a => 1, b => 2);
68             my @list = (1, 2);
69             $memd->set('hash', \%hash);
70             $memd->set_multi(['scalar', 1], ['list', \@list]);
71              
72             # Add to strings.
73             $memd->prepend('skey', 'This is a ');
74             $memd->prepend_multi(['skey2', 'This is a '], ['skey3', 'prefix ']);
75             $memd->append('skey', 'ue.');
76             $memd->append_multi(['skey2', 'ue.'], ['skey3', ' suffix']);
77              
78             # Do arithmetic.
79             $memd->incr('nkey', 10);
80             print "OK\n" if $memd->decr('nkey', 3) == 12;
81              
82             my @counters = qw(c1 c2);
83             $memd->set_multi(map { [$_, 0] } @counters, 'c3', 'c4');
84             $memd->incr_multi(['c3', 2], @counters, ['c4', 10]);
85              
86             # Retrieve values.
87             my $val = $memd->get('skey');
88             print "OK\n" if $val eq 'This is a value.';
89             my $href = $memd->get_multi('hash', 'nkey');
90             print "OK\n" if $href->{hash}->{b} == 2 and $href->{nkey} == 12;
91              
92             # Do atomic test-and-set operations.
93             my $cas_val = $memd->gets('nkey');
94             $$cas_val[1] = 0 if $$cas_val[1] == 12;
95             if ($memd->cas('nkey', @$cas_val)) {
96             print "OK, value updated\n";
97             } else {
98             print "Update failed, probably another client"
99             . " has updated the value\n";
100             }
101              
102             # Delete some data.
103             $memd->delete('skey');
104              
105             my @keys = qw(k1 k2 k3);
106             $memd->delete_multi(@keys);
107              
108             # Wait for all commands that were executed in nowait mode.
109             $memd->nowait_push;
110              
111             # Wipe out all cached data.
112             $memd->flush_all;
113              
114              
115             =head1 DESCRIPTION
116              
117             B is a Perl client for B, a memory
118             cache daemon (L). Module core is
119             implemented in C and tries hard to minimize number of system calls and
120             to avoid any key/value copying for speed. As a result, it has very
121             low CPU consumption.
122              
123             API is largely compatible with L,
124             original pure Perl client, most users of the original module may start
125             using this module by installing it and adding I<"::Fast"> to the old
126             name in their scripts (see L
127             below for full details).
128              
129              
130             =cut
131              
132              
133 17     17   109 use Carp;
  17         41  
  17         873  
134 17     17   9505 use Storable;
  17         47150  
  17         14693  
135              
136             require XSLoader;
137             XSLoader::load('Cache::Memcached::Fast', $VERSION);
138              
139              
140             =head1 CONSTRUCTOR
141              
142             =over
143              
144             =item C
145              
146             my $memd = new Cache::Memcached::Fast($params);
147              
148             Create new client object. I<$params> is a reference to a hash with
149             client parameters. Currently recognized keys are:
150              
151             =over
152              
153             =item I
154              
155             servers => [ { address => 'localhost:11211', weight => 2.5 },
156             '192.168.254.2:11211',
157             { address => '/path/to/unix.sock', noreply => 1 } ],
158             (default: none)
159              
160             The value is a reference to an array of server addresses. Each
161             address is either a scalar, a hash reference, or an array reference
162             (for compatibility with Cache::Memcached, deprecated). If hash
163             reference, the keys are I
(scalar), I (positive
164             rational number), and I (boolean flag). The server address
165             is in the form I for network TCP connections, or
166             F for local Unix socket connections. When weight
167             is not given, 1 is assumed. Client will distribute keys across
168             servers proportionally to server weights.
169              
170             If you want to get key distribution compatible with Cache::Memcached,
171             all server weights should be integer, and their sum should be less
172             than 32768.
173              
174             When I is enabled, commands executed in a void context will
175             instruct the server to not send the reply. Compare with L
176             below. B server implements I starting with
177             version 1.2.5. If you enable I for earlier server versions,
178             things will go wrongly, and the client will eventually block. Use
179             with care.
180              
181              
182             =item I
183              
184             namespace => 'my::'
185             (default: '')
186              
187             The value is a scalar that will be prepended to all key names passed
188             to the B server. By using different namespaces clients
189             avoid interference with each other.
190              
191              
192             =item I
193              
194             hash_namespace => 1
195             (default: disabled)
196              
197             The value is a boolean which enables (true) or disables (false) the
198             hashing of the namespace key prefix. By default for compatibility
199             with B namespace prefix is not hashed along with the
200             key. Thus
201              
202             namespace => 'prefix/',
203             ...
204             $memd->set('key', $val);
205              
206             may use different B server than
207              
208             namespace => '',
209             ...
210             $memd->set('prefix/key', $val);
211              
212             because hash values of I<'key'> and I<'prefix/key'> may be different.
213              
214             However sometimes is it necessary to hash the namespace prefix, for
215             instance for interoperability with other clients that do not have the
216             notion of the namespace. When I is enabled, both
217             examples above will use the same server, the one that I<'prefix/key'>
218             is mapped to. Note that there's no performance penalty then, as
219             namespace prefix is hashed only once. See L.
220              
221              
222             =item I
223              
224             nowait => 1
225             (default: disabled)
226              
227             The value is a boolean which enables (true) or disables (false)
228             I mode. If enabled, when you call a method that only returns
229             its success status (like L), B>, it sends
230             the request to the server and returns immediately, not waiting the
231             reply. This avoids the round-trip latency at a cost of uncertain
232             command outcome.
233              
234             Internally there is a counter of how many outstanding replies there
235             should be, and on any command the client reads and discards any
236             replies that have already arrived. When you later execute some method
237             in a non-void context, all outstanding replies will be waited for, and
238             then the reply for this command will be read and returned.
239              
240              
241             =item I
242              
243             connect_timeout => 0.7
244             (default: 0.25 seconds)
245              
246             The value is a non-negative rational number of seconds to wait for
247             connection to establish. Applies only to network connections. Zero
248             disables timeout, but keep in mind that operating systems have their
249             own heuristic connect timeout.
250              
251             Note that network connect process consists of several steps:
252             destination host address lookup, which may return several addresses in
253             general case (especially for IPv6, see
254             L and
255             L), then the
256             attempt to connect to one of those addresses. I
257             applies only to one such connect, i.e. to one I
258             call. Thus overall connect process may take longer than
259             I seconds, but this is unavoidable.
260              
261              
262             =item I (or deprecated I)
263              
264             io_timeout => 0.5
265             (default: 1.0 seconds)
266              
267             The value is a non-negative rational number of seconds to wait before
268             giving up on communicating with the server(s). Zero disables timeout.
269              
270             Note that for commands that communicate with more than one server
271             (like L) the timeout applies per server set, not per each
272             server. Thus it won't expire if one server is quick enough to
273             communicate, even if others are silent. But if some servers are dead
274             those alive will finish communication, and then dead servers would
275             timeout.
276              
277              
278             =item I
279              
280             close_on_error => 0
281             (default: enabled)
282              
283             The value is a boolean which enables (true) or disables (false)
284             I mode. When enabled, any error response from the
285             B server would make client close the connection. Note that
286             such "error response" is different from "negative response". The
287             latter means the server processed the command and yield negative
288             result. The former means the server failed to process the command for
289             some reason. I is enabled by default for safety.
290             Consider the following scenario:
291              
292             =over
293              
294             =item 1 Client want to set some value, but mistakenly sends malformed
295             command (this can't happen with current module of course ;)):
296              
297             set key 10\r\n
298             value_data\r\n
299              
300             =item 2 Memcached server reads first line, 'set key 10', and can't
301             parse it, because there's wrong number of tokens in it. So it
302             sends
303              
304             ERROR\r\n
305              
306             =item 3 Then the server reads 'value_data' while it is in
307             accept-command state! It can't parse it either (hopefully),
308             and sends another
309              
310             ERROR\r\n
311              
312             =back
313              
314             But the client expects one reply per command, so after sending the
315             next command it will think that the second 'ERROR' is a reply for this
316             new command. This means that all replies will shift, including
317             replies for L commands! By closing the connection we eliminate
318             such possibility.
319              
320             When connection dies, or the client receives the reply that it can't
321             understand, it closes the socket regardless the I
322             setting.
323              
324              
325             =item I
326              
327             compress_threshold => 10_000
328             (default: -1)
329              
330             The value is an integer. When positive it denotes the threshold size
331             in bytes: data with the size equal or larger than this should be
332             compressed. See L and L below.
333              
334             Negative value disables compression.
335              
336              
337             =item I
338              
339             compress_ratio => 0.9
340             (default: 0.8)
341              
342             The value is a fractional number between 0 and 1. When
343             L triggers the compression, compressed size
344             should be less or equal to S<(original-size * I)>.
345             Otherwise the data will be stored uncompressed.
346              
347              
348             =item I
349              
350             compress_methods => [ \&IO::Compress::Gzip::gzip,
351             \&IO::Uncompress::Gunzip::gunzip ]
352             (default: [ sub { ${$_[1]} = Compress::Zlib::memGzip(${$_[0]}) },
353             sub { ${$_[1]} = Compress::Zlib::memGunzip(${$_[0]}) } ]
354             when Compress::Zlib is available)
355              
356             The value is a reference to an array holding two code references for
357             compression and decompression routines respectively.
358              
359             Compression routine is called when the size of the I<$value> passed to
360             L method family is greater than or equal to
361             L (also see L). The fact that
362             compression was performed is remembered along with the data, and
363             decompression routine is called on data retrieval with L method
364             family. The interface of these routines should be the same as for
365             B family (for instance see
366             L and
367             L).
368             I.e. compression routine takes a reference to scalar value and a
369             reference to scalar where compressed result will be stored.
370             Decompression routine takes a reference to scalar with compressed data
371             and a reference to scalar where uncompressed result will be stored.
372             Both routines should return true on success, and false on error.
373              
374             By default we use L because as of this
375             writing it appears to be much faster than
376             L.
377              
378              
379             =item I
380              
381             max_failures => 3
382             (default: 0)
383              
384             The value is a non-negative integer. When positive, if there happened
385             I in I seconds, the client does not try
386             to connect to this particular server for another I
387             seconds. Value of zero disables this behaviour.
388              
389              
390             =item I
391              
392             failure_timeout => 30
393             (default: 10 seconds)
394              
395             The value is a positive integer number of seconds. See
396             L.
397              
398              
399             =item I
400              
401             ketama_points => 150
402             (default: 0)
403              
404             The value is a non-negative integer. When positive, enables the
405             B consistent hashing algorithm
406             (L), and
407             specifies the number of points the server with weight 1 will be mapped
408             to. Thus each server will be mapped to S *
409             I> points in continuum. Larger value will result in more
410             uniform distribution. Note that the number of internal bucket
411             structures, and hence memory consumption, will be proportional to sum
412             of such products. But bucket structures themselves are small (two
413             integers each), so you probably shouldn't worry.
414              
415             Zero value disables the Ketama algorithm. See also server weight in
416             L above.
417              
418              
419             =item I
420              
421             serialize_methods => [ \&Storable::freeze, \&Storable::thaw ],
422             (default: [ \&Storable::nfreeze, \&Storable::thaw ])
423              
424             The value is a reference to an array holding two code references for
425             serialization and deserialization routines respectively.
426              
427             Serialization routine is called when the I<$value> passed to L
428             method family is a reference. The fact that serialization was
429             performed is remembered along with the data, and deserialization
430             routine is called on data retrieval with L method family. The
431             interface of these routines should be the same as for
432             L and
433             L. I.e. serialization routine takes a
434             reference and returns a scalar string; it should not fail.
435             Deserialization routine takes scalar string and returns a reference;
436             if deserialization fails (say, wrong data format) it should throw an
437             exception (call I). The exception will be caught by the module
438             and L will then pretend that the key hasn't been found.
439              
440              
441             =item I
442              
443             utf8 => 1
444             (default: disabled)
445              
446             The value is a boolean which enables (true) or disables (false) the
447             conversion of Perl character strings to octet sequences in UTF-8
448             encoding on store, and the reverse conversion on fetch (when the
449             retrieved data is marked as being UTF-8 octet sequence). See
450             L.
451              
452              
453             =item I
454              
455             max_size => 512 * 1024
456             (default: 1024 * 1024)
457              
458             The value is a maximum size of an item to be stored in memcached.
459             When trying to set a key to a value longer than I bytes
460             (after serialization and compression) nothing is sent to the server,
461             and I methods return I.
462              
463             Note that the real maximum on the server is less than 1MB, and depends
464             on key length among other things. So some values in the range
465             S>, where N is several hundreds, will still be
466             sent to the server, and rejected there. You may set I to a
467             smaller value to avoid this.
468              
469              
470             =item I
471              
472             check_args => 'skip'
473             (default: not 'skip')
474              
475             The value is a string. Currently the only recognized string is
476             I<'skip'>.
477              
478             By default all constructor parameter names are checked to be
479             recognized, and a warning is given for unknown parameter. This will
480             catch spelling errors that otherwise might go unnoticed.
481              
482             When set to I<'skip'>, the check will be bypassed. This may be
483             desired when you share the same argument hash among different client
484             versions, or among different clients.
485              
486              
487             =back
488              
489             =back
490              
491             =cut
492              
493             our %known_params = (
494             servers => [ { address => 1, weight => 1, noreply => 1 } ],
495             namespace => 1,
496             nowait => 1,
497             hash_namespace => 1,
498             connect_timeout => 1,
499             io_timeout => 1,
500             select_timeout => 1,
501             close_on_error => 1,
502             compress_threshold => 1,
503             compress_ratio => 1,
504             compress_methods => 1,
505             compress_algo => sub {
506             carp "compress_algo has been removed in 0.08,"
507             . " use compress_methods instead"
508             },
509             max_failures => 1,
510             failure_timeout => 1,
511             ketama_points => 1,
512             serialize_methods => 1,
513             utf8 => 1,
514             max_size => 1,
515             check_args => 1,
516             );
517              
518              
519             sub _check_args {
520 63     63   113 my ($checker, $args, $level) = @_;
521              
522 63 100       174 $level = 0 unless defined $level;
523              
524 63         94 my @unknown;
525              
526 63 100       162 if (ref($args) ne 'HASH') {
527 32 100 66     164 if (ref($args) eq 'ARRAY' and ref($checker) eq 'ARRAY') {
528 16         45 foreach my $v (@$args) {
529 31         111 push @unknown, _check_args($checker->[0], $v, $level + 1);
530             }
531             }
532 32         108 return @unknown;
533             }
534              
535 31 50 33     123 if (exists $args->{check_args}
536             and lc($args->{check_args}) eq 'skip') {
537 0         0 return;
538             }
539              
540 31         138 while (my ($k, $v) = each %$args) {
541 213 50       328 if (exists $checker->{$k}) {
542 213 50       655 if (ref($checker->{$k}) eq 'CODE') {
    100          
543 0         0 $checker->{$k}->($args, $k, $v);
544             } elsif (ref($checker->{$k})) {
545 16         84 push @unknown, _check_args($checker->{$k}, $v, $level + 1);
546             }
547             } else {
548 0         0 push @unknown, $k;
549             }
550             }
551              
552 31 100       86 if ($level > 0) {
553 15         56 return @unknown;
554             } else {
555 16 50       173 carp "Unknown parameter: @unknown" if @unknown;
556             }
557             }
558              
559              
560             our %instance;
561              
562             sub new {
563 16     16 1 7171 my Cache::Memcached::Fast $class = shift;
564 16         37 my ($conf) = @_;
565              
566 16         49 _check_args(\%known_params, $conf);
567              
568 16 50 66     1077 if (not $conf->{compress_methods}
      66        
      66        
569             and defined $conf->{compress_threshold}
570             and $conf->{compress_threshold} >= 0
571             and eval "require Compress::Zlib") {
572             # Note that the functions below can't return false when
573             # operation succeed. This is because "" and "0" compress to a
574             # longer values (because of additional format data), and
575             # compress_ratio will force them to be stored uncompressed,
576             # thus decompression will never return them.
577             $conf->{compress_methods} = [
578 0     0   0 sub { ${$_[1]} = Compress::Zlib::memGzip(${$_[0]}) },
  0         0  
  0         0  
579 0     0   0 sub { ${$_[1]} = Compress::Zlib::memGunzip(${$_[0]}) }
  0         0  
  0         0  
580 15         810854 ];
581             }
582              
583 16 50 33     302 if ($conf->{utf8} and $^V lt v5.8.1) {
584 0         0 carp "'utf8' may be enabled only for Perl >= 5.8.1, disabled";
585 0         0 undef $conf->{utf8};
586             }
587              
588 16   100     142 $conf->{serialize_methods} ||= [ \&Storable::nfreeze, \&Storable::thaw ];
589              
590 16         1518 my $memd = Cache::Memcached::Fast::_new($class, $conf);
591              
592 16         70 my $context = [$memd, $conf];
593 16         87 _weaken($context->[0]);
594 16         111 $instance{$$memd} = $context;
595              
596 16         72 return $memd;
597             }
598              
599              
600             sub CLONE {
601 0     0   0 my ($class) = @_;
602              
603 0         0 my @contexts = values %instance;
604 0         0 %instance = ();
605 0         0 foreach my $context (@contexts) {
606 0         0 my $memd = Cache::Memcached::Fast::_new($class, $context->[1]);
607 0         0 ${$context->[0]} = $$memd;
  0         0  
608 0         0 $instance{$$memd} = $context;
609 0         0 $$memd = 0;
610             }
611             }
612              
613              
614             sub DESTROY {
615 16     16   14301 my ($memd) = @_;
616              
617 16 50       69 return unless $$memd;
618              
619 16         70 delete $instance{$$memd};
620              
621 16         745 Cache::Memcached::Fast::_destroy($memd);
622             }
623              
624              
625             =head1 METHODS
626              
627             =over
628              
629             =item C
630              
631             $memd->enable_compress($enable);
632              
633             Enable compression when boolean I<$enable> is true, disable when
634             false.
635              
636             Note that you can enable compression only when you set
637             L to some positive value and L
638             is set.
639              
640             I none.
641              
642             =cut
643              
644             # See Fast.xs.
645              
646              
647             =item C
648              
649             $memd->namespace;
650             $memd->namespace($string);
651              
652             Without the argument return the current namespace prefix. With the
653             argument set the namespace prefix to I<$string>, and return the old
654             prefix.
655              
656             I scalar, the namespace prefix that was in effect before the
657             call.
658              
659             =cut
660              
661             # See Fast.xs.
662              
663              
664             =item C
665              
666             $memd->set($key, $value);
667             $memd->set($key, $value, $expiration_time);
668              
669             Store the I<$value> on the server under the I<$key>. I<$key> should
670             be a scalar. I<$value> should be defined and may be of any Perl data
671             type. When it is a reference, the referenced Perl data structure will
672             be transparently serialized by routines specified with
673             L, which see.
674              
675             Optional I<$expiration_time> is a positive integer number of seconds
676             after which the value will expire and wouldn't be accessible any
677             longer.
678              
679             I boolean, true for positive server reply, false for negative
680             server reply, or I in case of some error.
681              
682             =cut
683              
684             # See Fast.xs.
685              
686              
687             =item C
688              
689             $memd->set_multi(
690             [$key, $value],
691             [$key, $value, $expiration_time],
692             ...
693             );
694              
695             Like L, but operates on more than one key. Takes the list of
696             references to arrays each holding I<$key>, I<$value> and optional
697             I<$expiration_time>.
698              
699             Note that multi commands are not all-or-nothing, some operations may
700             succeed, while others may fail.
701              
702             I in list context returns the list of results, each
703             I<$list[$index]> is the result value corresponding to the argument at
704             position I<$index>. In scalar context, hash reference is returned,
705             where I<$href-E{$key}> holds the result value. See L to
706             learn what the result value is.
707              
708             =cut
709              
710             # See Fast.xs.
711              
712              
713             =item C
714              
715             $memd->cas($key, $cas, $value);
716             $memd->cas($key, $cas, $value, $expiration_time);
717              
718             Store the I<$value> on the server under the I<$key>, but only if CAS
719             (I) value associated with this key is equal
720             to I<$cas>. I<$cas> is an opaque object returned with L or
721             L or L or L.
722              
723             See L for I<$key>, I<$value>, I<$expiration_time> parameters
724             description.
725              
726             I boolean, true for positive server reply, false for negative
727             server reply, or I in case of some error. Thus if the key
728             exists on the server, false would mean that some other client has
729             updated the value, and L, L, L command sequence should be
730             repeated.
731              
732             B command first appeared in B 1.2.4.
733              
734             =cut
735              
736             # See Fast.xs.
737              
738              
739             =item C
740              
741             $memd->cas_multi(
742             [$key, $cas, $value],
743             [$key, $cas, $value, $expiration_time],
744             ...
745             );
746              
747             Like L, but operates on more than one key. Takes the list of
748             references to arrays each holding I<$key>, I<$cas>, I<$value> and
749             optional I<$expiration_time>.
750              
751             Note that multi commands are not all-or-nothing, some operations may
752             succeed, while others may fail.
753              
754             I in list context returns the list of results, each
755             I<$list[$index]> is the result value corresponding to the argument at
756             position I<$index>. In scalar context, hash reference is returned,
757             where I<$href-E{$key}> holds the result value. See L to
758             learn what the result value is.
759              
760             B command first appeared in B 1.2.4.
761              
762             =cut
763              
764             # See Fast.xs.
765              
766              
767             =item C
768              
769             $memd->add($key, $value);
770             $memd->add($key, $value, $expiration_time);
771              
772             Store the I<$value> on the server under the I<$key>, but only if the
773             key B exists on the server.
774              
775             See L for I<$key>, I<$value>, I<$expiration_time> parameters
776             description.
777              
778             I boolean, true for positive server reply, false for negative
779             server reply, or I in case of some error.
780              
781             =cut
782              
783             # See Fast.xs.
784              
785              
786             =item C
787              
788             $memd->add_multi(
789             [$key, $value],
790             [$key, $value, $expiration_time],
791             ...
792             );
793              
794             Like L, but operates on more than one key. Takes the list of
795             references to arrays each holding I<$key>, I<$value> and optional
796             I<$expiration_time>.
797              
798             Note that multi commands are not all-or-nothing, some operations may
799             succeed, while others may fail.
800              
801             I in list context returns the list of results, each
802             I<$list[$index]> is the result value corresponding to the argument at
803             position I<$index>. In scalar context, hash reference is returned,
804             where I<$href-E{$key}> holds the result value. See L to
805             learn what the result value is.
806              
807             =cut
808              
809             # See Fast.xs.
810              
811              
812             =item C
813              
814             $memd->replace($key, $value);
815             $memd->replace($key, $value, $expiration_time);
816              
817             Store the I<$value> on the server under the I<$key>, but only if the
818             key B exists on the server.
819              
820             See L for I<$key>, I<$value>, I<$expiration_time> parameters
821             description.
822              
823             I boolean, true for positive server reply, false for negative
824             server reply, or I in case of some error.
825              
826             =cut
827              
828             # See Fast.xs.
829              
830              
831             =item C
832              
833             $memd->replace_multi(
834             [$key, $value],
835             [$key, $value, $expiration_time],
836             ...
837             );
838              
839             Like L, but operates on more than one key. Takes the list
840             of references to arrays each holding I<$key>, I<$value> and optional
841             I<$expiration_time>.
842              
843             Note that multi commands are not all-or-nothing, some operations may
844             succeed, while others may fail.
845              
846             I in list context returns the list of results, each
847             I<$list[$index]> is the result value corresponding to the argument at
848             position I<$index>. In scalar context, hash reference is returned,
849             where I<$href-E{$key}> holds the result value. See L to
850             learn what the result value is.
851              
852             =cut
853              
854             # See Fast.xs.
855              
856              
857             =item C
858              
859             $memd->append($key, $value);
860              
861             B the I<$value> to the current value on the server under the
862             I<$key>.
863              
864             I<$key> and I<$value> should be scalars, as well as current value on
865             the server. C doesn't affect expiration time of the value.
866              
867             I boolean, true for positive server reply, false for negative
868             server reply, or I in case of some error.
869              
870             B command first appeared in B 1.2.4.
871              
872             =cut
873              
874             # See Fast.xs.
875              
876              
877             =item C
878              
879             $memd->append_multi(
880             [$key, $value],
881             ...
882             );
883              
884             Like L, but operates on more than one key. Takes the list of
885             references to arrays each holding I<$key>, I<$value>.
886              
887             Note that multi commands are not all-or-nothing, some operations may
888             succeed, while others may fail.
889              
890             I in list context returns the list of results, each
891             I<$list[$index]> is the result value corresponding to the argument at
892             position I<$index>. In scalar context, hash reference is returned,
893             where I<$href-E{$key}> holds the result value. See L to
894             learn what the result value is.
895              
896             B command first appeared in B 1.2.4.
897              
898             =cut
899              
900             # See Fast.xs.
901              
902              
903             =item C
904              
905             $memd->prepend($key, $value);
906              
907             B the I<$value> to the current value on the server under the
908             I<$key>.
909              
910             I<$key> and I<$value> should be scalars, as well as current value on
911             the server. C doesn't affect expiration time of the value.
912              
913             I boolean, true for positive server reply, false for negative
914             server reply, or I in case of some error.
915              
916             B command first appeared in B 1.2.4.
917              
918             =cut
919              
920             # See Fast.xs.
921              
922              
923             =item C
924              
925             $memd->prepend_multi(
926             [$key, $value],
927             ...
928             );
929              
930             Like L, but operates on more than one key. Takes the list
931             of references to arrays each holding I<$key>, I<$value>.
932              
933             Note that multi commands are not all-or-nothing, some operations may
934             succeed, while others may fail.
935              
936             I in list context returns the list of results, each
937             I<$list[$index]> is the result value corresponding to the argument at
938             position I<$index>. In scalar context, hash reference is returned,
939             where I<$href-E{$key}> holds the result value. See L to
940             learn what the result value is.
941              
942             B command first appeared in B 1.2.4.
943              
944             =cut
945              
946             # See Fast.xs.
947              
948              
949             =item C
950              
951             $memd->get($key);
952              
953             Retrieve the value for a I<$key>. I<$key> should be a scalar.
954              
955             I value associated with the I<$key>, or nothing.
956              
957             =cut
958              
959             # See Fast.xs.
960              
961              
962             =item C
963              
964             $memd->get_multi(@keys);
965              
966             Retrieve several values associated with I<@keys>. I<@keys> should be
967             an array of scalars.
968              
969             I reference to hash, where I<$href-E{$key}> holds
970             corresponding value.
971              
972             =cut
973              
974             # See Fast.xs.
975              
976              
977             =item C
978              
979             $memd->gets($key);
980              
981             Retrieve the value and its CAS for a I<$key>. I<$key> should be a
982             scalar.
983              
984             I reference to an array I<[$cas, $value]>, or nothing. You
985             may conveniently pass it back to L with I<@$res>:
986              
987             my $cas_val = $memd->gets($key);
988             # Update value.
989             if (defined $cas_val) {
990             $$cas_val[1] = 3;
991             $memd->cas($key, @$cas_val);
992             }
993              
994             B command first appeared in B 1.2.4.
995              
996             =cut
997              
998             # See Fast.xs.
999              
1000              
1001             =item C
1002              
1003             $memd->gets_multi(@keys);
1004              
1005             Retrieve several values and their CASs associated with I<@keys>.
1006             I<@keys> should be an array of scalars.
1007              
1008             I reference to hash, where I<$href-E{$key}> holds a
1009             reference to an array I<[$cas, $value]>. Compare with L.
1010              
1011             B command first appeared in B 1.2.4.
1012              
1013             =cut
1014              
1015             # See Fast.xs.
1016              
1017              
1018             =item C
1019              
1020             $memd->incr($key);
1021             $memd->incr($key, $increment);
1022              
1023             Increment the value for the I<$key>. Starting with B 1.3.3
1024             I<$key> should be set to a number or the command will fail. An
1025             optional I<$increment> should be a positive integer, when not given 1
1026             is assumed. Note that the server doesn't check for overflow.
1027              
1028             I unsigned integer, new value for the I<$key>, or false for
1029             negative server reply, or I in case of some error.
1030              
1031             =cut
1032              
1033             # See Fast.xs.
1034              
1035              
1036             =item C
1037              
1038             $memd->incr_multi(
1039             @keys,
1040             [$key],
1041             [$key, $increment],
1042             ...
1043             );
1044              
1045             Like L, but operates on more than one key. Takes the list of
1046             keys and references to arrays each holding I<$key> and optional
1047             I<$increment>.
1048              
1049             Note that multi commands are not all-or-nothing, some operations may
1050             succeed, while others may fail.
1051              
1052             I in list context returns the list of results, each
1053             I<$list[$index]> is the result value corresponding to the argument at
1054             position I<$index>. In scalar context, hash reference is returned,
1055             where I<$href-E{$key}> holds the result value. See L to
1056             learn what the result value is.
1057              
1058             =cut
1059              
1060             # See Fast.xs.
1061              
1062              
1063             =item C
1064              
1065             $memd->decr($key);
1066             $memd->decr($key, $decrement);
1067              
1068             Decrement the value for the I<$key>. Starting with B 1.3.3
1069             I<$key> should be set to a number or the command will fail. An
1070             optional I<$decrement> should be a positive integer, when not given 1
1071             is assumed. Note that the server I check for underflow, attempt
1072             to decrement the value below zero would set the value to zero.
1073             Similar to L, zero is returned as I<"0E0">, and evaluates to
1074             true in a boolean context.
1075              
1076             I unsigned integer, new value for the I<$key>, or false for
1077             negative server reply, or I in case of some error.
1078              
1079             =cut
1080              
1081             # See Fast.xs.
1082              
1083              
1084             =item C
1085              
1086             $memd->decr_multi(
1087             @keys,
1088             [$key],
1089             [$key, $decrement],
1090             ...
1091             );
1092              
1093             Like L, but operates on more than one key. Takes the list of
1094             keys and references to arrays each holding I<$key> and optional
1095             I<$decrement>.
1096              
1097             Note that multi commands are not all-or-nothing, some operations may
1098             succeed, while others may fail.
1099              
1100             I in list context returns the list of results, each
1101             I<$list[$index]> is the result value corresponding to the argument at
1102             position I<$index>. In scalar context, hash reference is returned,
1103             where I<$href-E{$key}> holds the result value. See L to
1104             learn what the result value is.
1105              
1106             =cut
1107              
1108             # See Fast.xs.
1109              
1110              
1111             =item C
1112              
1113             $memd->delete($key);
1114              
1115             Delete I<$key> and its value from the cache.
1116              
1117             I boolean, true for positive server reply, false for negative
1118             server reply, or I in case of some error.
1119              
1120             =cut
1121              
1122             # See Fast.xs.
1123              
1124              
1125             =item C (B)
1126              
1127             Alias for L, for compatibility with B.
1128              
1129             =cut
1130              
1131             *remove = \&delete;
1132              
1133              
1134             =item C
1135              
1136             $memd->delete_multi(@keys);
1137              
1138             Like L, but operates on more than one key. Takes the list of
1139             keys.
1140              
1141             Note that multi commands are not all-or-nothing, some operations may
1142             succeed, while others may fail.
1143              
1144             I in list context returns the list of results, each
1145             I<$list[$index]> is the result value corresponding to the argument at
1146             position I<$index>. In scalar context, hash reference is returned,
1147             where I<$href-E{$key}> holds the result value. See L to
1148             learn what the result value is.
1149              
1150             =cut
1151              
1152             # See Fast.xs.
1153              
1154              
1155             =item C
1156              
1157             $memd->touch($key, $expiration_time);
1158              
1159             Update the expiration time of I<$key> without fetching it.
1160              
1161             Optional I<$expiration_time> is a positive integer number of seconds
1162             after which the value will expire and wouldn't be accessible any
1163             longer.
1164              
1165             I boolean, true for positive server reply, false for negative
1166             server reply, or I in case of some error.
1167              
1168             B command first appeared in B 1.4.8.
1169              
1170             =cut
1171              
1172             # See Fast.xs.
1173              
1174              
1175             =item C
1176              
1177             $memd->touch_multi(
1178             [$key],
1179             [$key, $expiration_time],
1180             ...
1181             );
1182              
1183             Like L, but operates on more than one key. Takes the list of
1184             references to arrays each holding I<$key> and optional I<$expiration_time>.
1185              
1186             Note that multi commands are not all-or-nothing, some operations may
1187             succeed, while others may fail.
1188              
1189             I in list context returns the list of results, each
1190             I<$list[$index]> is the result value corresponding to the argument at
1191             position I<$index>. In scalar context, hash reference is returned,
1192             where I<$href-E{$key}> holds the result value. See L to
1193             learn what the result value is.
1194              
1195             B command first appeared in B 1.4.8.
1196              
1197             =cut
1198              
1199             # See Fast.xs.
1200              
1201              
1202             =item C
1203              
1204             $memd->gat($expiration_time, $key);
1205              
1206             Update the expiration time and retrieve the value for a I<$key>.
1207              
1208             I<$key> should be a scalar. I<$expiration_time> is a positive integer number
1209             of seconds after which the value will expire and wouldn't be accessible any
1210             longer.
1211              
1212             I value associated with the I<$key>, or nothing.
1213              
1214             B command first appeared in B 1.5.3.
1215              
1216             =cut
1217              
1218             # See Fast.xs.
1219              
1220             =item C
1221              
1222             $memd->gat_multi($expiration_time, @keys);
1223              
1224             Update the expiration time of the I<@keys> and get the associated values.
1225             I<@keys> should be an array of scalars.
1226              
1227             I reference to hash, where I<$href-E{$key}> holds
1228             corresponding value.
1229              
1230             B command first appeared in B 1.5.3.
1231              
1232             # See Fast.xs.
1233              
1234              
1235             =item C
1236              
1237             $memd->gets($expiration_time, $key);
1238              
1239             Update the expiration time and Retrieve the value and its CAS for a I<$key>.
1240              
1241             I reference to an array I<[$cas, $value]>, or nothing. You
1242             may conveniently pass it back to L with I<@$res>:
1243              
1244             my $cas_val = $memd->gats($expiration_time, $key);
1245             # Update value.
1246             if (defined $cas_val) {
1247             $$cas_val[1] = 3;
1248             $memd->cas($key, @$cas_val);
1249             }
1250              
1251             B command first appeared in B 1.5.3.
1252              
1253             # See Fast.xs.
1254              
1255              
1256             =item C
1257              
1258             $memd->gats_multi($expiration_time, @keys);
1259              
1260             Update the expiration time and retrieve several values and their CASs
1261             associated with I<@keys>.
1262             I<@keys> should be an array of scalars.
1263              
1264             I reference to hash, where I<$href-E{$key}> holds a
1265             reference to an array I<[$cas, $value]>. Compare with L.
1266              
1267             B command first appeared in B 1.5.3.
1268              
1269             # See Fast.xs.
1270              
1271              
1272             =item C
1273              
1274             $memd->flush_all;
1275             $memd->flush_all($delay);
1276              
1277             Flush all caches the client knows about. This command invalidates all
1278             items in the caches, none of them will be returned on subsequent
1279             retrieval command. I<$delay> is an optional non-negative integer
1280             number of seconds to delay the operation. The delay will be
1281             distributed across the servers. For instance, when you have three
1282             servers, and call C, the servers would get 30, 15, 0
1283             seconds delays respectively. When omitted, zero is assumed,
1284             i.e. flush immediately.
1285              
1286             I reference to hash, where I<$href-E{$server}> holds
1287             corresponding result value. I<$server> is either I or
1288             F, as described in L. Result value is a
1289             boolean, true for positive server reply, false for negative server
1290             reply, or I in case of some error.
1291              
1292             =cut
1293              
1294             # See Fast.xs.
1295              
1296              
1297             =item C
1298              
1299             $memd->nowait_push;
1300              
1301             Push all pending requests to the server(s), and wait for all replies.
1302             When L mode is enabled, the requests issued in a void context
1303             may not reach the server(s) immediately (because the reply is not
1304             waited for). Instead they may stay in the send queue on the local
1305             host, or in the receive queue on the remote host(s), for quite a long
1306             time. This method ensures that they are delivered to the server(s),
1307             processed there, and the replies have arrived (or some error has
1308             happened that caused some connection(s) to be closed).
1309              
1310             Destructor will call this method to ensure that all requests are
1311             processed before the connection is closed.
1312              
1313             I nothing.
1314              
1315             =cut
1316              
1317             # See Fast.xs.
1318              
1319              
1320             =item C
1321              
1322             $memd->server_versions;
1323              
1324             Get server versions.
1325              
1326             I reference to hash, where I<$href-E{$server}> holds
1327             corresponding server version. I<$server> is either I or
1328             F, as described in L.
1329              
1330             =cut
1331              
1332             # See Fast.xs.
1333              
1334              
1335             =item C
1336              
1337             $memd->disconnect_all;
1338              
1339             Closes all open sockets to memcached servers. Must be called after
1340             L if the parent process has open sockets to memcacheds (as the
1341             child process inherits the socket and thus two processes end up using the same
1342             socket which leads to protocol errors.)
1343              
1344             I nothing.
1345              
1346             =cut
1347              
1348             # See Fast.xs.
1349              
1350              
1351             1;
1352              
1353             __END__