Shade - Memcached Client for Scala

Overview

Shade is a Memcached client based on the de-facto Java library SpyMemcached.

The interface exposed is very Scala-ish, as you have a choice between making asynchronous calls, with results wrapped as Scala Futures, or blocking calls. The performance is stellar as it benefits from the optimizations that went into SpyMemcached over the years. Shade also fixes some problems with SpyMemcached's architecture, choices that made sense in the context of Java, but don't make so much sense in the context of Scala (TODO: add details).

The client is production quality. Supported for Scala versions: 2.10, 2.11 and 2.12.

Release Notes

Maintainers

These are the people maintaining this project that you can annoy:

Alex: @alexandru
Lloyd: @lloydmeta

Usage From SBT

dependencies += "io.monix" %% "shade" % "1.10.0"

Initializing the Memcached Client

To initialize a Memcached client, you need a configuration object. Checkout the Configuration case class.

import shade.memcached._
import scala.concurrent.ExecutionContext.Implicits.global

val memcached =
  Memcached(Configuration("127.0.0.1:11211"))

As you can see, you also need an ExecutionContext passed explicitly. As an implementation detail, the execution context represents the thread-pool in which requests get processed.

Simple non-blocking requests

Useful imports:

import concurrent.duration._ // for specifying timeouts
import concurrent.Future

Setting a key:

val op: Future[Unit] = memcached.set("username", "Alex", 1.minute)

Adding a key that will only set it if the key is missing (returns true if the key was added, or false if the key was already there):

val op: Future[Boolean] = memcached.add("username", "Alex", 1.minute)

Deleting a key (returns true if a key was deleted, or false if the key was missing):

val op: Future[Boolean] = memcached.delete("username")

Fetching a key:

val result: Future[Option[String]] = memcached.get[String]("username")

As you can see, for fetching a key the get() method needs an explicit type parameter, otherwise it doesn't know how to deserialize it. More on this below.

Blocking requests

Sometimes working with Futures is painful for quick hacks, therefore add(), set(), delete() and get() have blocking versions in the form of awaitXXX():

memcached.awaitGet("username") match {
  case Some(username) => println(s"Hello, $username")
  case None =>
    memcached.awaitSet("username", "Alex", 1.minute)
}

Compare-and-set

Sometimes you want to have some sort of synchronization for modifying values safely, like incrementing a counter. Memcached supports Compare-And-Swap atomic operations and so does this client.

val op: Future[Boolean] =
  memcached.compareAndSet("username", Some("Alex"), "Amalia", 1.minute)

This will return either true or false if the operation was a success or not. But working with compareAndSet is too low level, so the client also provides these helpers:

def incrementCounter: Future[Int] =
  memcached.transformAndGet[Int]("counter", 1.minute) {
    case Some(existing) => existing + 1
    case None => 1
  }

The above returns the new, incremented value. In case you want the old value to be returned, do this:

def incrementCounter: Future[Option[Int]] =
  memcached.getAndTransform[Int]("counter", 1.minute) {
    case Some(existing) => existing + 1
    case None => 1
  }

Serializing/Deserializing

Storing values in Memcached and retrieving values involves serializing and deserializing those values into bytes. Methods such as get(), set(), add() take an implicit parameter of type Codec[T] which is a type-class that specifies how to serialize and deserialize values of type T.

By default, Shade provides default implementations of Codec[T] for primitives, such as Strings and numbers. Checkout Codec.scala to see those defaults.

For more complex types, a default implementation based on Java's ObjectOutputStream and ObjectInputStream exist (also in Codec.scala).

However, because serializing/deserializing values like this is problematic (you can end up with lots of errors related to the ClassLoader used), this codec is available as part of the MemcachedCodecs trait (also in Codec.scala) and it either needs to be imported or mixed-in.

The import works like so:

import shade.memcached.MemcachedCodecs._

But this can land you in trouble because of the ClassLoader. For example in a Play 2.x application, in development mode the code is recompiled when changes happen and the whole environment gets restarted. If you do a plain import, you'll get ClassCastException or other weird errors. You can solve this by mixing-in MemcachedCodecs in whatever trait, class or object you want to do requests, as in:

case class User(id: Int, name: String, age: Int)

trait HelloController extends Controller with MemcachedCodecs {
   def memcached: Memcached // to be injected

   // a Play 2.2 standard controller action
   def userInfo(id: Int) = Action.async {
     for (user <-  memcached.get[User]("user-" + id)) yield
       Ok(views.showUserDetails(user))
   }

   // ...
}

Or, in case you want to optimize serialization/deserialization, you can always implement your own Codec[T], like:

// hackish example
implicit object UserCodec extends Codec[User] {
  def serialize(user: User): Array[Byte] =
    s"${user.id}|${user.name}|${user.age}".getBytes("utf-8")

  def deserialize(data: Array[Byte]): User = {
    val str = new String(data, "utf-8")
    val Array(id, name, age) = str.split("|")
    User(id.toInt, name, age.toInt)
  }
}

monix / shade

readme