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. It allows connections to entire Memcached clusters and supports connection pools, timeouts, and failover.

Install

Module-aware mode:

$ go get github.com/memcachier/mc/v3

Legacy GOPATH mode:

$ go get github.com/memcachier/mc

Use

import "github.com/memcachier/mc/v3"
// Legacy GOPATH mode:
// import "github.com/memcachier/mc"

func main() {
	// Error handling omitted for demo

	// Only PLAIN SASL auth supported right now
	c := mc.NewMC("localhost:11211", "username", "password")
	defer c.Quit()

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

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

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

Missing Feature

There is nearly coverage of the Memcached protocol. 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. There is however support for connection pools which should make up for it.

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 MemCachier. 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
• func NewModuloHasher() hasher
• type Client
  • func NewMC(servers, username, password string) *Client
  • func NewMCwithConfig(servers, username, password string, config *Config) *Client
  • func (c *Client) Add(key, val string, flags, exp uint32) (cas uint64, err error)
  • func (c *Client) Append(key, val string, ocas uint64) (cas uint64, err error)
  • func (c *Client) Decr(key string, delta, init uint64, exp uint32, ocas uint64) (n, cas uint64, err error)
  • func (c *Client) Del(key string) (err error)
  • func (c *Client) DelCAS(key string, cas uint64) (err error)
  • func (c *Client) Flush(when uint32) (err error)
  • func (c *Client) GAT(key string, exp uint32) (val string, flags uint32, cas uint64, err error)
  • func (c *Client) Get(key string) (val string, flags uint32, cas uint64, err error)
  • func (c *Client) Incr(key string, delta, init uint64, exp uint32, ocas uint64) (n, cas uint64, err error)
  • func (c *Client) NoOp() (err error)
  • func (c *Client) Prepend(key, val string, ocas uint64) (cas uint64, err error)
  • func (c *Client) Quit()
  • func (c *Client) Replace(key, val string, flags, exp uint32, ocas uint64) (cas uint64, err error)
  • func (c *Client) Set(key, val string, flags, exp uint32, ocas uint64) (cas uint64, err error)
  • func (c *Client) Stats() (stats map[string]McStats, err error)
  • func (c *Client) StatsReset() (err error)
  • func (c *Client) StatsWithKey(key string) (map[string]McStats, error)
  • func (c *Client) Touch(key string, exp uint32) (cas uint64, err error)
  • func (c *Client) Version() (vers map[string]string, err error)
• type Config
  • func DefaultConfig() *Config
• type Error
  • func (err Error) Error() string
• type McStats

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.

Functions

func NewModuloHasher

func NewModuloHasher() hasher

Types

type Client

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

Client represents a memcached client that is connected to a list of servers

func NewMC

func NewMC(servers, username, password string) *Client

NewMC creates a new client with the default configuration. For the default configuration see DefaultConfig.

func NewMCwithConfig

func NewMCwithConfig(servers, username, password string, config *Config) *Client

NewMCwithConfig creates a new client for a given configuration

func (*Client) Add

func (c *Client) 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 (*Client) Append

func (c *Client) 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 (*Client) Decr

func (c *Client) 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 (*Client) Del

func (c *Client) Del(key string) (err error)

Del deletes a key/value from the cache.

func (*Client) DelCAS

func (c *Client) 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 (*Client) Flush

func (c *Client) 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 (*Client) GAT

func (c *Client) 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 (*Client) Get

func (c *Client) Get(key string) (val string, flags uint32, cas uint64, err error)

Get retrieves a value from the cache.

func (*Client) Incr

func (c *Client) 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 (*Client) NoOp

func (c *Client) 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 (*Client) Prepend

func (c *Client) 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 (*Client) Quit

func (c *Client) Quit()

Quit closes the connection with memcached server (nicely).

func (*Client) Replace

func (c *Client) 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 (*Client) Set

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

Set sets a key/value pair in the cache.

func (*Client) Stats

func (c *Client) Stats() (stats map[string]McStats, err error)

Stats returns some statistics about the memcached server.

func (*Client) StatsReset

func (c *Client) StatsReset() (err error)

StatsReset resets the statistics stored at the memcached server.

func (*Client) StatsWithKey

func (c *Client) StatsWithKey(key string) (map[string]McStats, 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 (*Client) Touch

func (c *Client) Touch(key string, exp uint32) (cas uint64, err error)

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

func (*Client) Version

func (c *Client) Version() (vers map[string]string, err error)

Version gets the version of the memcached server connected to.

type Config

type Config struct {
	Hasher     hasher
	Retries    int
	RetryDelay time.Duration
	Failover   bool
	// ConnectionTimeout is currently used to timeout getting connections from
	// pool, as a sending deadline and as a reading deadline. Worst case this
	// means a request can take 3 times the ConnectionTimeout.
	ConnectionTimeout  time.Duration
	DownRetryDelay     time.Duration
	PoolSize           int
	TcpKeepAlive       bool
	TcpKeepAlivePeriod time.Duration
	TcpNoDelay         bool
}

Config holds the Memcache client configuration. Use DefaultConfig to get an initialized version.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a config object populated with the default values. The default values currently are:

config{
	Hasher:             NewModuloHasher(),
	Retries:            2,
	RetryDelay:         200 * time.Millisecond,
	Failover:           true,
	ConnectionTimeout:  2 * time.Second,
	DownRetryDelay:     60 * time.Second,
	PoolSize:           1,
	TcpKeepAlive:       true,
	TcpKeepAlivePeriod: 60 * time.Second,
	TcpNoDelay:         true,
}

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).

type McStats

type McStats map[string]string

Memcache stats