govindsharma7 / smile

actor-based memcache client library

SMILE

Smile is a memcache library for scala which is intended to be fast and highly concurrent. It is open-sourced under the Apache 2 license.

All the standard key hashing functions are supported (CRC-ITU, FNV, and Ketama). Support for round-robin ("default") and Ketama key distributions is built-in. User-defined key hashing and distribution functions can be trivially added via the API.

Server lists and configuration may be set manually or via configgy blocks. User-defined key hashing and distribution may be specified in the config block -- just be sure to add them via the API first! :)

Author: Robey Pointer [email protected]

Strategy

Mina is used as a library for handling asynchronous I/O via java NIO, and the memcache protocol is implemented using the naggati DSL for building Mina protocol state machines. I/O events are forwarded to scala actors, with one actor for each memcache server connection. It acts like a thread-pool but ensures that each server's traffic is handled sequentially, with very simple code.

Performance

A performance test is included as an ant target. It requires you to have 3 memcached servers running on localhost, on ports 11211, 11212, and 11213:

$ ant manygets
manygets:
     [java] serial gets: 1000
     [java] toasters: 1000 in 797 msec (0.80 msec each)
     [java] parallel gets: 1000 on 10 threads
     [java] toasters: 10000 in 2992 msec (0.30 msec each)
     [java] parallel gets: 1000 on 10 threads from 3 servers
     [java] toasters: 10000 in 2048 msec (0.20 msec each)

The first test does 1000 memcache "get" operations in a row, from a single thread. The second does 1000 each from 10 different threads, to verify that performance increases. The third does the same test but randomly picks one of three memcache servers for each "get", to simulate a real-world environment where you would have more than one memcache server, and could run operations on each server in parallel.

API

To get/set UTF-8 strings using a single-node memcache cluster on localhost:

val cache = MemcacheClient.create(Array("localhost"), "default", "crc32-itu")
cache.set("name", "smile")
cache.get("name")

Configuration

Configuration can be done with a configgy block, like so:

memcache {
  distribution = "ketama"
  hash = "fnv1a-64"
  namespace = "widgets:"
  servers = [ "memcache1:11211", "memcache2:11211", "memcache3:11211" ]
}

The name "memcache" is arbitrary -- use whatever name you want, and pass the nested block into MemcacheClient.create.

Config settings:

• distribution - algorithm for finding a server for a key; builtin distributions are "modulo", "ketama", and "sequential", or you can add your own
• hash - hash function to use when determining the server; builtin functions are "crc32-itu", "ketama", "fnv1-32", "fnv1a-32", "fnv1-64", "fnv1a-64"
• namespace - optional prefix to put in front of each key before hashing
• servers - list of memcache servers
• retry_delay_sec - when we fail to connect to a server, how many seconds should we wait before trying again; all requests to that server will fail immediately in the interim
• read_timeout_msec - timeout for reading server responses before giving up and raising an exception
• connect_timeout_msec - timeout for waiting for a connection to a server before giving up and raising an exception
• max_failures_before_ejection - number of consecutive times a server can throw an exception before that server is removed from the pool (for retry_delay_sec seconds)
• trace - true if smile should log all bytes sent/received for trace-level debugging

TO-DO

• Support more than just get and set. At least delete, add, and append.

• Expose the stats command in some useful way.