About this guide

This guide combines an overview of Spyglass with a quick tutorial that helps you to get started with it. It should take about 15 minutes to read and study the provided code examples. This guide covers:

  • Features of Spyglass
  • Clojure and Memcached Server version requirements
  • How to add Spyglass dependency to your project
  • A very brief introduction to Spyglass capabilities
  • Examples of the most common Memcached operations with Spyglass

This work is licensed under a Creative Commons Attribution 3.0 Unported License (including images & stylesheets). The source is available on Github.

What version of Spyglass does this guide cover?

This guide covers Spyglass 1.0.0-rc2 and later 1.0.x releases.

Spyglass Overview

Spyglass is an idiomatic Clojure client for Memcached. It is simple and easy to use, strives to support every Memcached protocol feature, both text and binary protocols as well as offer asynchronous and synchronous APIs for most operations.

Spyglass gets its name from and is based on on Spy Memcached, a mature, heavily tested and very fast Java client for Memcached. Spyglass' overhead is very very low.

You can use Spyglass with servers that use the Memcached protocol, for example, Membase Server or Kestrel messaging queue.

Supported Clojure versions

Spyglass is built from the ground up for Clojure 1.3 and later.

Supported Memcached versions

Spyglass supports Memcached 1.4.x (1.4.13 or later are recommended). Some features (like binary protocol support) may require specific point versions. See the list of Memcached 1.4.x release notes to learn more.

Adding Neocons Dependency To Your Project

With Leiningen

[clojurewerkz/spyglass "1.0.0"]

With Maven

<dependency>
  <groupId>clojurewerkz</groupId>
  <artifactId>spyglass</artifactId>
  <version>1.0.0</version>
</dependency>

It is recommended to stay up-to-date with new versions. New releases and important changes are announced @ClojureWerkz.

Connecting to Memcached

Spyglass has a single namespace: clojurewerkz.spyglass.client. Require it and use the clojurewerkz.spyglass.client/text-connection function that take a server list string:

clojurewerkz.spyglass.client/bin-connection works the same way but uses binary Memcached protocol:

Setting keys

To set a key, use the clojurewerkz.spyglass.client/set function that takes a client instance, a string key, an expiration value (as an integer) and a value to store and returns a future:

Expiration values

The actual expiration value sent may either be Unix time (number of seconds since January 1, 1970, as a 32-bit value), or a number of seconds starting from current time. In the latter case, this number of seconds may not exceed 60*60*24*30 (number of seconds in 30 days); if the number sent by a client is larger than that, the server will consider it to be real Unix time value rather than an offset from current time.

Transcoders

TBD

Getting keys

Synchronous get

To get a value synchronously, use the clojurewerkz.spyglass.client/get function that takes a client instance, a string key, and returns a stored value:

Asynchronous get

Spyglass also provides a way to fetch a value asynchronously using the clojurewerkz.spyglass.client/async-get function that the same arguments but returns a future:

Getting multiple keys in a single operation

Synchronous multi-get

It is possible to get multiple values in a single request using the clojurewerkz.spyglass.client/get-multi function that takes a client instance, a collection of keys, and returns an immutable map of stored values:

Asynchronous multi-get

Asynchronous multi-get is available via the clojurewerkz.spyglass.client/async-get-multi function that returns a future that, when dereferenced, returns a map of results:

Deleting keys

To delete a key, use the clojurewerkz.spyglass.client/delete function that has the same signature as (2-arity) clojurewerkz.spyglass.client/get:

Delete operations are always asynchronous and always return a future.

Touching (updating expiration time) keys

To touch a key means to reset or update its expiration time using the clojurewerkz.spyglass.client/touch function:

When touching keys, values lower than 60*60*24*30 are treated as relative offset (a number of seconds starting from current time) and values greater than that are treated as absolute Unix timestamps.

add operation

Sometimes you only need to add a value to the cache but only if does not already exist. This is what the clojurewerkz.spyglass.client/add function does in a single request:

This function returns a future that, when dereferenced, returns a boolean (false if the mutation did not occur, true if it did).

replace operation

clojurewerkz.spyglass.client/replace is similar to clojurewerkz.spyglass.client/add but will replace a value with the given one if there is already a value for the given key:

This function returns a future that, when dereferenced, returns a boolean (false if the mutation did not occur, true if it did).

gets and CAS (compare-and-swap) operations

TBD

increments, decrements operations

TBD

Getting stats

TBD

Disconnecting from Memcached

To disconnect, use the clojurewerkz.spyglass.client/shutdown function:

It is also possible to let all running asynchronous operations to finish by disconnecting with a timeout:

Wrapping up

Congratulations, you now can use Spyglass to work with Memcached or other servers that use (e.g. Membase Server or Kestrel messaging queue). Now you know enough to start building a real application.

We hope you find Spyglass reliable, consistent and easy to use. In case you need help, please ask on the mailing list and follow us on Twitter @ClojureWerkz.

Tell Us What You Think!

Please take a moment to tell us what you think about this guide on Twitter or the Spyglass mailing list

Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is key to making the documentation better.