Added method to obtain most recent result message (NOT_FOUND etc).

lib/Cache/Memcached.pm

 # $Id$
 #
 # Copyright (c) 2003, 2004  Brad Fitzpatrick <brad@danga.com>
 #
 # See COPYRIGHT section in pod text below for usage and distribution rights.
 #
 
 package Cache::Memcached;
 
 use strict;
 use warnings;
 
 no strict 'refs';
 use Storable ();
 use Socket qw( MSG_NOSIGNAL PF_INET PF_UNIX IPPROTO_TCP SOCK_STREAM );
 use IO::Handle ();
 use Time::HiRes ();
 use String::CRC32;
 use Errno qw( EINPROGRESS EWOULDBLOCK EISCONN );
 use Cache::Memcached::GetParser;
 use fields qw{
     debug no_rehash stats compress_threshold compress_enable stat_callback
     readonly select_timeout namespace namespace_len servers active buckets
     pref_ip
     bucketcount _single_sock _stime
     connect_timeout cb_connect_fail
     parser_class
+    last_res
 };
 
 # flag definitions
 use constant F_STORABLE => 1;
 use constant F_COMPRESS => 2;
 
 # size savings required before saving compressed value
 use constant COMPRESS_SAVINGS => 0.20; # percent
 
 use vars qw($VERSION $HAVE_ZLIB $FLAG_NOSIGNAL);
@@ skipping 41 matching lines @@
 
     # TODO: undocumented
     $self->{'connect_timeout'} = $args->{'connect_timeout'} || 0.25;
     $self->{'select_timeout'}  = $args->{'select_timeout'}  || 1.0;
     $self->{namespace} = $args->{namespace} || '';
     $self->{namespace_len} = length $self->{namespace};
 
     return $self;
 }
 
+sub last_res {

[brad_danga_com, 2009/02/28 15:58:41]

"res" is a great internal abbreviations but it's a terrible symbol to let leak
out in a public API.  This should be renamed to "last_result" probably.

[markaufflick, 2009/03/02 00:04:12]

Fair point - i'll change that.

On 2009/02/28 15:58:41, bradfitz wrote:

+    my Cache::Memcached $self = shift;
+
+    return $self->{last_res};
+}
+
 sub set_pref_ip {
     my Cache::Memcached $self = shift;
     $self->{'pref_ip'} = shift;
 }
 
 sub set_servers {
     my Cache::Memcached $self = shift;
     my ($list) = @_;
     $self->{'servers'} = $list || [];
     $self->{'active'} = scalar @{$self->{'servers'}};
@@ skipping 235 matching lines @@
 
 # writes a line, then reads result.  by default stops reading after a
 # single line, but caller can override the $check_complete subref,
 # which gets passed a scalarref of buffer read thus far.
 sub _write_and_read {
     my Cache::Memcached $self = shift;
     my ($sock, $line, $check_complete) = @_;
     my $res;
     my ($ret, $offset) = (undef, 0);
 
+    $self->{last_res} = undef;
+
     $check_complete ||= sub {
         return (rindex($ret, "\r\n") + 2 == length($ret));
     };
 
     # state: 0 - writing, 1 - reading, 2 - done
     my $state = 0;
 
     # the bitsets for select
     my ($rin, $rout, $win, $wout);
     my $nfound;
@@ skipping 40 matching lines @@
             $offset += $res;
             $state = 2 if $check_complete->(\$ret);
         }
     }
 
     unless ($state == 2) {
         _dead_sock($sock); # improperly finished
         return undef;
     }
 
+    $self->{last_res} = $ret;
+    $self->{last_res} =~ s/\r\n$//;

[brad_danga_com, 2009/02/28 15:58:41]

Performance suggestion:  It might make more sense to only do the \r\n stripping
lazily, when the user actually calls the "last_result" method, so you avoid the
regexp in the common case (of the user not calling the method).

[markaufflick, 2009/03/02 00:04:12]

Also a good suggestion.

On 2009/02/28 15:58:41, bradfitz wrote:

+
     return $ret;
 }
 
 sub delete {
     my Cache::Memcached $self = shift;
     my ($key, $time) = @_;
     return 0 if ! $self->{'active'} || $self->{'readonly'};
     my $stime = Time::HiRes::time() if $self->{'stat_callback'};
     my $sock = $self->get_sock($key);
     return 0 unless $sock;
@@ skipping 672 matching lines @@
 is not checked.  Be aware of values approaching 2**32.  See decr.
 
 =item C<decr>
 
 $memd->decr($key[, $value]);
 
 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.
 
+=item C<last_res>
+
+$memd->last_res
+
+This method returns the status string of the last operation except for get(s).

[brad_danga_com, 2009/02/28 15:58:41]

So this only works with the ASCII protocol?  You should be explicit about that. 
Perhaps document that if this module were ever to support the binary protocol,
this method would continue to return the ASCII *equivalent* status code, even if
the library decided to speak binary behind the scenes.

[markaufflick, 2009/03/02 00:04:12]

The whole module has no support or mention of the binary protocol, but I would
envision binary support to work the way you mention. No point having a pile of
constants that have to be exported/imported when we can use the simple strings
of the ascii protocol.

I'll include some sort of comment to that effect.

On 2009/02/28 15:58:41, bradfitz wrote:

+This allows you, for instance, to differentiate between C<NOT_FOUND> and a
+protocol error. The trailing \r\n has already been removed. See the
+memcached protocol docs for possible return values for each command:
+L<http://code.sixapart.com/svn/memcached/trunk/server/doc/protocol.txt>
+
 =item C<stats>
 
 $memd->stats([$keys]);
 
 Returns a hashref of statistical data regarding the memcache server(s),
 the $memd object, or both.  $keys can be an arrayref of keys wanted, a
 single key wanted, or absent (in which case the default value is malloc,
 sizes, self, and the empty string).  These keys are the values passed
 to the 'stats' command issued to the memcached server(s), except for
 'self' which is internal to the $memd object.  Allowed values are:
@@ skipping 82 matching lines @@
 
 =head1 AUTHORS
 
 Brad Fitzpatrick <brad@danga.com>
 
 Anatoly Vorobey <mellon@pobox.com>
 
 Brad Whitaker <whitaker@danga.com>
 
 Jamie McCarthy <jamie@mccarthy.vg>