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.
These are the people maintaining this project that you can annoy:
- Alex: @alexandru
- Lloyd: @lloydmeta
dependencies += "io.monix" %% "shade" % "1.10.0"
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.
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.
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)
}
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
}
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)
}
}