Cache::Memcached(3)

📦
version 1.30 · 8 versions
, in opensuse-leap 16.0

💖 Cache::Memcached — the Perl client for memcached, bestie edition 💖

okay so. this is Cache::Memcached, a User Contributed Perl Documentation page, and it's literally the Perl API for talking to memcached. slay. let's get into it 🫶

✨ NAME ✨

Cache::Memcached — client library for memcached (memory cache daemon). that's it, that's the vibe 💅

🦋 SYNOPSIS 🦋

  use Cache::Memcached;

  $memd = new Cache::Memcached {
    'servers' => [ "10.0.0.15:11211", "10.0.0.15:11212", "/var/sock/memcached",
                   "10.0.0.17:11211", [ "10.0.0.17:11211", 3 ] ],
    'debug' => 0,
    'compress_threshold' => 10_000,
  };
  $memd->set_servers($array_ref);
  $memd->set_compress_threshold(10_000);
  $memd->enable_compress(0);

  $memd->set("my_key", "Some value");
  $memd->set("object_key", { 'complex' => [ "object", 2, 4 ]});

  $val = $memd->get("my_key");
  $val = $memd->get("object_key");
  if ($val) { print $val->{'complex'}->[2]; }

  $memd->incr("key");
  $memd->decr("key");
  $memd->incr("key", 2);

look at all that. iconic behavior honestly 😭

🌸 DESCRIPTION 🌸

This is the Perl API for memcached, a distributed memory cache daemon. more info lives here:

  http://www.danga.com/memcached/

🎀 CONSTRUCTOR 🎀

💜 new

Takes one parameter — a hashref of options. the most important key is servers, but no stress, you can also set that later with the set_servers method.

the servers must be an arrayref of hosts, and each host is either:

  • a scalar like "10.0.0.10:11211", or
  • an arrayref of that scalar plus an integer weight value. (the default weight if you don't specify one is 1.)
⚠️ real talk: it's recommended that you keep weight values as low as possible, because this module currently allocates memory for bucket distribution proportional to the total host weights. lowkey important, ngl.

Use compress_threshold to set a compression threshold, in bytes. values larger than this threshold get compressed by set and decompressed by get. cute ✨

Use no_rehash to disable finding a new memcached server when one goes down. your app may or may not need this, depending on your expirations and key usage. iykyk.

Use readonly to disable writes to backend memcached servers. only get and get_multi will work. this is useful in bizarre debug and profiling cases only. like, niche niche 🙈

Use namespace to prefix all keys with the provided namespace value. that is, if you set namespace to "app1:" and later do a set of "foo" to "bar", memcached is actually seeing you set "app1:foo" to "bar". the way it just quietly prefixes everything, obsessed 💅

Use connect_timeout and select_timeout to set connection and polling timeouts. connect_timeout defaults to .25 second, and select_timeout defaults to 1 second.

the other useful key is debug, which when set to true will produce diagnostics on STDERR. 🩺

🔥 METHODS 🔥

💖 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 new constructor. same shape, different day 🫶

💖 set_debug

Sets the debug flag. see new constructor for more information.

💖 set_readonly

Sets the readonly flag. see new constructor for more information.

💖 set_norehash

Sets the no_rehash flag. see new constructor for more information.

💖 set_compress_threshold

Sets the compression threshold. see new constructor for more information.

💖 set_connect_timeout

Sets the connect timeout. see new constructor for more information.

💖 set_select_timeout

Sets the select timeout. see new constructor for more information.

💖 enable_compress

Temporarily enable or disable compression. has no effect if compress_threshold isn't set, but has an overriding effect if it is. the way it just overrides everything when it feels like it 💀

💖 get

  my $val = $memd->get($key);

Retrieves a key from the memcache. returns the value (automatically thawed with Storable, if necessary) or undef. ✨

the $key 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. main character key-routing energy 👑

💖 get_multi

  my $hashref = $memd->get_multi(@keys);

Retrieves multiple keys from the memcache doing just one query. returns a hashref of key/value pairs that were available. 🎀

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. fewer packets, less waiting, we love to see it 🦋

💖 set

  $memd->set($key, $value[, $exptime]);

Unconditionally sets a key to a given value in the memcache. returns true if it was stored successfully. no cap, no conditions 💅

the $key can optionally be an arrayref, with the first element being the hash value, as described above.

the $exptime (expiration time) defaults to "never" if unspecified. if you want the key to expire in memcached, pass an integer $exptime. 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. ⏰

💖 add

  $memd->add($key, $value[, $exptime]);

Like set, but only stores in memcache if the key doesn't already exist. it's giving "new friend only" energy 🫶

💖 replace

  $memd->replace($key, $value[, $exptime]);

Like set, but only stores in memcache if the key already exists. the opposite of add. 🔁

💖 delete

  $memd->delete($key[, $time]);

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.

you may also use the alternate method name remove, so Cache::Memcached looks like the Cache::Cache API. yes bestie, two names, same slay ✨

💖 incr

  $memd->incr($key[, $value]);

Sends a command to the server to atomically increment the value for $key by $value, or by 1 if $value is undefined. returns undef if $key 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.

💖 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. it simply refuses to go negative, periodt 🧚

💖 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:

  • "misc" — the stats returned by a 'stats' command: pid, uptime, version, bytes, get_hits, etc.
  • "malloc" — the stats returned by a 'stats malloc': total_alloc, arena_size, etc.
  • "sizes" — the stats returned by a 'stats sizes'.
  • "self" — the stats for the $memd object itself (a copy of $memd->{'stats'}).
  • "maps" — the stats returned by a 'stats maps'.
  • "cachedump" — the stats returned by a 'stats cachedump'.
  • "slabs" — the stats returned by a 'stats slabs'.
  • "items" — the stats returned by a 'stats items'.

so many stats, so little time 📊

💖 disconnect_all

  $memd->disconnect_all;

Closes all cached sockets to all memcached servers.

🚨 you must do this if your program forks and the parent has used this module at all. otherwise the children will try to use cached sockets and they'll fight (as children do) and garble the client/server protocol. literally siblings in the back seat 😭

💖 flush_all

  $memd->flush_all;

Runs the memcached "flush_all" command on all configured hosts, emptying all their caches. (or rather, invalidating all items in the caches in an O(1) operation...) running stats will still show the item existing, they're just be non-existent and lazily destroyed next time you try to detch any of them. okay so they're like Schrödinger's cache entries 💀

🙈 BUGS 🙈

When a server goes down, this module does detect it, and re-hashes the request to the remaining servers, but the way it does it isn't very clean. the result may be that it gives up during its rehashing and refuses to get/set something it could've, had it been done right. not me calling out the rehash algorithm 🙈

This module is Copyright (c) 2003 Brad Fitzpatrick. All rights reserved. 💖

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

🌈 WARRANTY 🌈

This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND. say it louder for the people in the back 🗣️

🍓 FAQ 🍓

See the memcached website:

   http://www.danga.com/memcached/

⭐ AUTHORS ⭐

  • Brad Fitzpatrick <brad@danga.com>
  • Anatoly Vorobey <mellon@pobox.com>
  • Brad Whitaker <whitaker@danga.com>
  • Jamie McCarthy <jamie@mccarthy.vg>

okay that's the whole page bestie, you're officially memcached-literate 💅✨

🎀 and a lil sign-off from the page itself: this here is Cache::Memcached(3), rendered by perl v5.42.0, dated 2015-04-17. vintage but iconic 🫶
📦 where this page comes from