The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Protocol-Memcached-0.004
River stage one • 1 direct dependent • 2 total dependents
++
/ Protocol::Memcached

NAME

Protocol::Memcached - memcached binary protocol implementation

VERSION

version 0.004

SYNOPSIS

 package Subclass::Of::Protocol::Memcached;
 use parent qw(Protocol::Memcached);

 sub write { $_[0]->{socket}->write($_[1]) }

 package main;
 my $mc = Subclass::Of::Protocol::Memcached->new;
 my ($k, $v) = ('hello' => 'world');
 $mc->set(
        $k => $v,
        on_complete     => sub {
                $mc->get(
                        'key',
                        on_complete     => sub { my $v = shift; print "Had $v\n" },
                        on_error        => sub { die "Failed because of @_\n" }
                );
        }
 );

DESCRIPTION

Bare minimum protocol support for memcached. This class is transport-agnostic and as such is not a working implementation - you need to subclass and provide your own ->write method.

If you're using this class, you're most likely doing it wrong - head over to the "SEE ALSO" section to rectify this.

Protocol::Memcached::Client is probably the module you want if you are going to subclass this.

SUBCLASSING

Provide the following method:

write

This will be called with the data to be written, and zero or more named parameters:

  • on_flush - coderef to execute when the data has left the building, if this is not supported by the transport layer then the subclass should call the coderef before returning

and when you have data, call "on_read".

METHODS

new

Bare minimum constructor - subclass may need to inherit from something with a non-trivial constructor, so we put all our init code in "init".

sap

Helper method for weak callbacks.

get

Retrieves a value from memcached.

Takes a key and zero or more optional named parameters:

  • on_write - called when we've sent the request to the server

set

Retrieves a value from memcached.

Takes a key and zero or more optional named parameters:

  • on_write - called when we've sent the request to the server

init

Sets things up.

Currently just does some internal housekeeping, takes no parameters, and returns $self.

on_read

This should be called when there is data to be processed. It takes a single parameter: a reference to a buffer containing the incoming data. If a packet is processed successfully then it will be removed from this buffer (via substr or s// ).

Returns true if a packet was found, false if not. It is recommended (but not required) that this method be called repeatedly until it returns false.

status_text

Returns the status message corresponding to the given code.

build_packet

Generic packet construction.

hash_key

Returns a hashed version of the given key using md5.

ketama

Provided for backward compatibility only. See "hash_key".

build_ketama_map

Generates a Ketama hash map from the given list of servers.

Returns an arrayref of points.

ketama_hashi

Calculates an integer hash value from the given key.

ketama_find_point

Given a key value, calculates the closest point on the Ketama map.

WHY

Three main reasons:

  • Transport-agnostic - purposefully does not get involved in the details of sending or receiving data, when it wants to write something it'll call write, and when you have data to process you call on_read

  • Nonblocking - since this just operates on data and callbacks, rather than getting involved in transporting data, all operations should return quickly (in Perl terms)

  • Debugging support - strap this over a memcached transport layer and see human-readable versions of the binary packets

If you're looking for good performance, stability, an extensive set of tests, support, and a pony, then you're reading the wrong module:

SEE ALSO

AUTHOR

Tom Molesworth <cpan@entitymodel.com>

LICENSE

Copyright Tom Molesworth 2011-2012. Licensed under the same terms as Perl itself.