mc

README

mc.go: A Go client for Memcached

This is a (pure) Go client for Memcached. It supports the binary Memcached protocol and SASL authentication. It's thread-safe.

Install

	$ go get github.com/memcachier/mc

Use

	import "github.com/memcachier/mc"

	func main() {
		// Error handling omitted for demo
		cn, err := mc.Dial("tcp", "localhost:11211")
		if err != nil {
			...
		}

		// Only PLAIN SASL auth supported right now
		// See: http://code.google.com/p/memcached/wiki/SASLHowto
		err = cn.Auth("foo", "bar")
		if err != nil {
			...
		}
		

		val, cas, err = cn.Get("foo")
		if err != nil {
			...
		}

		exp = 3600 // 2 hours
		err = cn.Set("foo", "bar", cas, exp)
		if err != nil {
			...
		}

		err = cn.Del("foo")
		if err != nil {
			...
		}
	}

Missing Feature

There is nearly coverage of the Memcached protocol, but at the moment we only support a single Memcached server. Support for a Memcached cluster using a sharding / hashing method is still needed.

The biggest missing protocol feature is support for multi_get and other batched operations.

There is also no support for asynchronous IO.

Performance

Right now we use a single per-connection mutex and don't support pipe-lining any operations.

Get involved!

We are happy to receive bug reports, fixes, documentation enhancements, and other improvements.

Please report bugs via the github issue tracker.

Master git repository:

• git clone git://github.com/memcachier/mc.git

Licensing

This library is MIT-licensed.

Authors

This library is written and maintained by David Terei (code@davidterei.com). It was originally written by Blake Mizerany.

Documentation

Overview

Package mc is a memcache client for Go supporting binary protocol and SASL authentication.

Index

• Constants
• Variables
• type Conn
  • func Dial(nett, addr string) (*Conn, error)
  • func NewConnection(conn io.ReadWriteCloser) *Conn
  • func (cn *Conn) Add(key, val string, flags, exp uint32) (cas uint64, err error)
  • func (cn *Conn) Append(key, val string, ocas uint64) (cas uint64, err error)
  • func (cn *Conn) Auth(user, pass string) error
  • func (cn *Conn) Close() error
  • func (cn *Conn) Decr(key string, delta, init uint64, exp uint32, ocas uint64) (n, cas uint64, err error)
  • func (cn *Conn) Del(key string) (err error)
  • func (cn *Conn) DelCAS(key string, cas uint64) (err error)
  • func (cn *Conn) Flush(when uint32) (err error)
  • func (cn *Conn) GAT(key string, exp uint32) (val string, flags uint32, cas uint64, err error)
  • func (cn *Conn) Get(key string) (val string, flags uint32, cas uint64, err error)
  • func (cn *Conn) Incr(key string, delta, init uint64, exp uint32, ocas uint64) (n, cas uint64, err error)
  • func (cn *Conn) NoOp() (err error)
  • func (cn *Conn) Prepend(key, val string, ocas uint64) (cas uint64, err error)
  • func (cn *Conn) Quit() (err error)
  • func (cn *Conn) Replace(key, val string, flags, exp uint32, ocas uint64) (cas uint64, err error)
  • func (cn *Conn) Set(key, val string, flags, exp uint32, ocas uint64) (cas uint64, err error)
  • func (cn *Conn) Stats() (stats map[string]string, err error)
  • func (cn *Conn) StatsReset() (err error)
  • func (cn *Conn) StatsWithKey(key string) (stats map[string]string, err error)
  • func (cn *Conn) Touch(key string, exp uint32) (cas uint64, err error)
  • func (cn *Conn) Version() (ver string, err error)
• type Error
  • func (err Error) Error() string

Constants

const (
	StatusOK             = uint16(0)
	StatusNotFound       = uint16(1)
	StatusKeyExists      = uint16(2)
	StatusValueTooLarge  = uint16(3)
	StatusInvalidArgs    = uint16(4)
	StatusValueNotStored = uint16(5)
	StatusNonNumeric     = uint16(6)
	StatusAuthRequired   = uint16(0x20)
	StatusAuthContinue   = uint16(0x21)
	StatusUnknownCommand = uint16(0x81)
	StatusOutOfMemory    = uint16(0x82)
	StatusAuthUnknown    = uint16(0xffff)
	StatusNetworkError   = uint16(0xfff1)
	StatusUnknownError   = uint16(0xffff)
)

Status Codes that may be returned (usually as part of an Error).

Variables

var (
	ErrNotFound       = &Error{StatusNotFound, "mc: not found", nil}
	ErrKeyExists      = &Error{StatusKeyExists, "mc: key exists", nil}
	ErrValueTooLarge  = &Error{StatusValueNotStored, "mc: value to large", nil}
	ErrInvalidArgs    = &Error{StatusInvalidArgs, "mc: invalid arguments", nil}
	ErrValueNotStored = &Error{StatusValueNotStored, "mc: value not stored", nil}
	ErrNonNumeric     = &Error{StatusNonNumeric, "mc: incr/decr called on non-numeric value", nil}
	ErrAuthRequired   = &Error{StatusAuthRequired, "mc: authentication required", nil}
	ErrAuthContinue   = &Error{StatusAuthContinue, "mc: authentication continue (unsupported)", nil}
	ErrUnknownCommand = &Error{StatusUnknownCommand, "mc: unknown command", nil}
	ErrOutOfMemory    = &Error{StatusOutOfMemory, "mc: out of memory", nil}
	ErrUnknownError   = &Error{StatusUnknownError, "mc: unknown error from server", nil}
)

Errors mc may return. Some errors aren't represented here as the message is dynamically generated. Status Code however captures all possible values for Error.Status.

Types

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn is a connection to a memcache server.

func Dial

func Dial(nett, addr string) (*Conn, error)

Dial establishes a connection to a memcache server.

func NewConnection

func NewConnection(conn io.ReadWriteCloser) *Conn

NewConnection establishes a new connections to a memcache server.

func (*Conn) Add

func (cn *Conn) Add(key, val string, flags, exp uint32) (cas uint64, err error)

Add adds a new key/value to the cache. Fails if the key already exists in the cache.

func (*Conn) Append

func (cn *Conn) Append(key, val string, ocas uint64) (cas uint64, err error)

Append appends the value to the existing value for the key specified. An error is thrown if the key doesn't exist.

func (*Conn) Auth

func (cn *Conn) Auth(user, pass string) error

Auth performs SASL authentication (using the PLAIN method) with the server.

func (*Conn) Close

func (cn *Conn) Close() error

Close closes the memcache connection.

func (*Conn) Decr

func (cn *Conn) Decr(key string, delta, init uint64, exp uint32, ocas uint64) (n, cas uint64, err error)

Decr decrements a value in the cache. The value must be an unsigned 64bit integer stored as an ASCII string. It can't be decremented below 0.

func (*Conn) Del

func (cn *Conn) Del(key string) (err error)

Del deletes a key/value from the cache.

func (*Conn) DelCAS

func (cn *Conn) DelCAS(key string, cas uint64) (err error)

DelCAS deletes a key/value from the cache but only if the CAS specified matches the CAS in the cache.

func (*Conn) Flush

func (cn *Conn) Flush(when uint32) (err error)

Flush flushes the cache, that is, invalidate all keys. Note, this doesn't typically free memory on a memcache server (doing so compromises the O(1) nature of memcache). Instead nearly all servers do lazy expiration, where they don't free memory but won't return any keys to you that have expired.

func (*Conn) GAT

func (cn *Conn) GAT(key string, exp uint32) (val string, flags uint32, cas uint64, err error)

GAT (get and touch) retrieves the value associated with the key and updates its expiration time.

func (*Conn) Get

func (cn *Conn) Get(key string) (val string, flags uint32, cas uint64, err error)

Get retrieves a value from the cache.

func (*Conn) Incr

func (cn *Conn) Incr(key string, delta, init uint64, exp uint32, ocas uint64) (n, cas uint64, err error)

Incr increments a value in the cache. The value must be an unsigned 64bit integer stored as an ASCII string. It will wrap when incremented outside the range.

func (*Conn) NoOp

func (cn *Conn) NoOp() (err error)

NoOp sends a No-Op message to the memcache server. This can be used as a heartbeat for the server to check it's functioning fine still.

func (*Conn) Prepend

func (cn *Conn) Prepend(key, val string, ocas uint64) (cas uint64, err error)

Prepend prepends the value to the existing value for the key specified. An error is thrown if the key doesn't exist.

func (*Conn) Quit

func (cn *Conn) Quit() (err error)

Quit closes the connection with memcache server (nicely).

func (*Conn) Replace

func (cn *Conn) Replace(key, val string, flags, exp uint32, ocas uint64) (cas uint64, err error)

Replace replaces an existing key/value in the cache. Fails if key doesn't already exist in cache.

func (*Conn) Set

func (cn *Conn) Set(key, val string, flags, exp uint32, ocas uint64) (cas uint64, err error)

Set sets a key/value pair in the cache.

func (*Conn) Stats

func (cn *Conn) Stats() (stats map[string]string, err error)

Stats returns some statistics about the memcached server.

func (*Conn) StatsReset

func (cn *Conn) StatsReset() (err error)

StatsReset resets the statistics stored at the memcached server.

func (*Conn) StatsWithKey

func (cn *Conn) StatsWithKey(key string) (stats map[string]string, err error)

StatsWithKey returns some statistics about the memcached server. It supports sending across a key to the server to select which statistics should be returned.

func (*Conn) Touch

func (cn *Conn) Touch(key string, exp uint32) (cas uint64, err error)

Touch updates the expiration time on a key/value pair in the cache.

func (*Conn) Version

func (cn *Conn) Version() (ver string, err error)

Version gets the version of the memcached server connected to.

type Error

type Error struct {
	Status       uint16
	Message      string
	WrappedError error
}

Error represents a MemCache error (including the status code). All function in mc return error values of this type, despite the functions using the plain error type. You can safely cast all error types returned by mc to *Error. If needed, we take an underlying error value (such as a network error) and wrap it in Error, storing the underlying value in WrappedError.

error is used as the return typed instead of Error directly due to the limitation in Go where error(nil) != *Error(nil).

func (Error) Error

func (err Error) Error() string

Error returns a human readable reason for the error (part of the error interface).