AnyEve...mcached(3pm)

💖 AnyEvent::Memcached 💖

okay bestie, gather round, because we are talking about AnyEvent::Memcached — literally the AnyEvent memcached client, and yes she is THAT girl. 🎀

It's a Perl module (3pm, iykyk) and it's here to make your async memcached dreams come true. Let's get into it. ✨

---

🌸 SYNOPSIS 🌸

okay so here's the whole vibe in code. Copy it, love it, live it:

use AnyEvent::Memcached;

my $memd = AnyEvent::Memcached->new(
    servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ], # same as in Cache::Memcached
    debug   => 1,
    compress_threshold => 10000,
    namespace => 'my-namespace:',

    # May use another hashing algo:
    hasher  => 'AnyEvent::Memcached::Hash::WithNext',

    cv      => $cv, # AnyEvent->condvar: group callback
);

$memd->set_servers([ "10.0.0.15:11211", "10.0.0.15:11212" ]);

# Basic methods are like in Cache::Memcached, but with additional cb => sub { ... };
# first argument to cb is return value, second is the error(s)

$memd->set( key => $value, cb => sub {
    shift or warn "Set failed: @_"
} );

# Single get
$memd->get( 'key', cb => sub {
    my ($value,$err) = shift;
    $err and return warn "Get failed: @_";
    warn "Value for key is $value";
} );

# Multi-get
$memd->get( [ 'key1', 'key2' ], cb => sub {
    my ($values,$err) = shift;
    $err and return warn "Get failed: @_";
    warn "Value for key1 is $values->{key1} and value for key2 is $values->{key2}"
} );

# Additionally there is rget (see memcachedb-1.2.1-beta)

$memd->rget( 'fromkey', 'tokey', cb => sub {
    my ($values,$err) = shift;
    $err and warn "Get failed: @_";
    while (my ($key,$value) = each %$values) {
        # ...
    }
} );

# Rget with sorted response values
$memd->rget( 'fromkey', 'tokey', rv => 'array' cb => sub {
    my ($values,$err) = shift;
    $err and warn "Get failed: @_";
    for (0 .. $#values/2) {
        my ($key,$value) = @$values[$_*2,$_*2+1];
    }
} );

---

🦋 DESCRIPTION 🦋

She's an asynchronous "memcached/memcachedb" client for the AnyEvent framework. That's the whole thing. Asynchronous. Memcached. AnyEvent. Periodt. 💅

---

👑 NOTICE 👑

There's a notice over in Cache::Memcached::AnyEvent that's related to this module, and bestie… they all have been fixed. All of them. Slay. ✨

💜 Prerequisites

We no longer need Object::Event and Devel::Leak::Cb. At all. Not even a little bit. The dependency list is like in Cache::Memcached + AnyEvent. Clean, simple, iconic.

💜 Binary protocol

ngl, it seems to me that usage of binary protocol from pure perl gives very little advantage. So for now, I don't implement it. That's just the tea. 🍓

💜 Unimplemented Methods

There's a note floating around that get_multi is not implementeted (their spelling, not mine 😭). In fact, it was implemented by method "get" — the documentation was just wrong. So like… it's fine, the docs just lied a lil. 🙈

💜 In general

This module follows the spirit of AnyEvent rather than correspondence to the Cache::Memcached interface. Main character energy, honestly. She does her own thing. 💅

---

✨ METHODS ✨

🌈 new %args

Currently supported options:

• servers
• namespace
• debug
• cv
• compress_threshold
• compress_enable
• timeout
• hasher — If set, will use instance of this class for hashing instead of default. For implementing your own hashing, see sources of AnyEvent::Memcached::Hash and AnyEvent::Memcached::Hash::With::Next
• noreply — If true, additional connection will established for noreply commands.
• cas — If true, will enable cas/gets commands (since they are not suppotred in memcachedb)

---

🌈 set_servers

Setup server list. That's it, that's the job. 🫶

---

🌈 connect

Establish connection to all servers and invoke event connected, when ready.

---

🌈 set( $key, $value, [cv => $cv], [ expire => $expire ], cb => $cb->( $rc, $err ) )

Unconditionally sets a key to a given value in the memcache. No questions asked, no conditions, she just goes. 💖

$rc is:

• '1' — Successfully stored
• '0' — Item was not stored
• undef — Error happens, see $err

---

🌈 cas( $key, $cas, $value, [cv => $cv], [ expire => $expire ], cb => $cb->( $rc, $err ) )

okay so the classic check-and-set flow looks like this:

$memd->gets($key, cb => sub {
    my $value = shift;
    unless (@_) { # No errors
        my ($cas,$val) = @$value;
        # Change your value in $val
        $memd->cas( $key, $cas, $value, cb => sub {
            my $rc = shift;
            if ($rc) {
                # stored
            } else {
                # ...
            }
        });
    }
})

$rc is the same, as for "set".

Store the $value on the server under the $key, but only if CAS value associated with this key is equal to $cas. See also "gets". Very demure, very mindful. 🧚

---

🌈 add( $key, $value, [cv => $cv], [ expire => $expire ], cb => $cb->( $rc, $err ) )

Like "set", but only stores in memcache if the key doesn't already exist.

---

🌈 replace( $key, $value, [cv => $cv], [ expire => $expire ], cb => $cb->( $rc, $err ) )

Like "set", but only stores in memcache if the key already exists. The opposite of add. Yin and yang, fr fr. ☯️

---

🌈 append( $key, $value, [cv => $cv], [ expire => $expire ], cb => $cb->( $rc, $err ) )

Append the $value to the current value on the server under the $key.

append command first appeared in memcached 1.2.4.

---

🌈 prepend( $key, $value, [cv => $cv], [ expire => $expire ], cb => $cb->( $rc, $err ) )

Prepend the $value to the current value on the server under the $key.

prepend command first appeared in memcached 1.2.4.

---

🌈 get( $key, [cv => $cv], [ expire => $expire ], cb => $cb->( $rc, $err ) )

Retrieve the value for a $key. $key should be a scalar.

---

🌈 get( $keys : ARRAYREF, [cv => $cv], [ expire => $expire ], cb => $cb->( $values_hash, $err ) )

Retrieve the values for a $keys. Return a hash with keys/values. Multi-get girlies rise up. 🔥

---

🌈 gets( $key, [cv => $cv], [ expire => $expire ], cb => $cb->( $rc, $err ) )

Retrieve the value and its CAS for a $key. $key should be a scalar.

$rc is a reference to an array [$cas, $value], or nothing for non-existent key.

---

🌈 gets( $keys : ARRAYREF, [cv => $cv], [ expire => $expire ], cb => $cb->( $rc, $err ) )

Retrieve the values and their CAS for a $keys.

$rc is a hash reference with $rc->{$key} is a reference to an array [$cas, $value].

---

🌈 delete( $key, [cv => $cv], [ noreply => 1 ], cb => $cb->( $rc, $err ) )

Delete $key and its value from the cache. Gone. Poof. 💀

If "noreply" is true, cb doesn't required.

---

🌈 del

Alias for "delete".

---

🌈 remove

Alias for "delete".

---

🌈 incr( $key, $increment, [cv => $cv], [ noreply => 1 ], cb => $cb->( $rc, $err ) )

Increment the value for the $key by $delta. Starting with memcached 1.3.3 $key should be set to a number or the command will fail. Note that the server doesn't check for overflow. 👀

If "noreply" is true, cb doesn't required, and if passed, simply called with rc = 1.

Similar to DBI, zero is returned as "0E0", and evaluates to true in a boolean context. Sneaky but iconic.

---

🌈 decr( $key, $decrement, [cv => $cv], [ noreply => 1 ], cb => $cb->( $rc, $err ) )

Opposite to "incr".

---

🌈 rget( $from, $till, [ max => 100 ], [ '+left' => 1 ], [ '+right' => 1 ], [cv => $cv], [ rv => 'array' ], cb => $cb->( $rc, $err ) )

Memcachedb 1.2.1-beta implements rget method, that allows one to look through the whole storage. Like a lil window into everything. 🪟

• $from — the starting key
• $till — finishing key
• +left — If true, then starting key will be included in results. true by default
• +right — If true, then finishing key will be included in results. true by default
• max — Maximum number of results to fetch. 100 is the maximum and is the default
• rv — If passed rv => 'array', then the return value will be arrayref with values in order, returned by memcachedb.

---

🌈 incadd ( $key, $increment, [cv => $cv], [ noreply => 1 ], cb => $cb->( $rc, $err ) )

Increment key, and if it not exists, add it with initial value. If add fails, try again to incr or fail. She's persistent, okay?? 💅

---

🌈 destroy

Shutdown object as much, as possible, incl cleaning of incapsulated objects. Basically logging off. 🫶

---

💀 BUGS 💀

• Feature requests are welcome
• Bug reports are welcome

---

🌸 AUTHOR 🌸

Mons Anderson, "<mons at cpan.org>"

---

🎀 COPYRIGHT & LICENSE 🎀

Copyright 2009 Mons Anderson, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie!! 🦋✨ this lil doc was brought to you by perl v5.34.0, dated 2022-06-06, from the AnyEve...mcached(3pm) corner of the world. mwah. 💖💅🌟