cluster

Documentation

Overview

Package cluster implements an almost drop-in replacement for a normal Client which accounts for a redis cluster setup. It will transparently redirect requests to the correct nodes, as well as keep track of which slots are mapped to which nodes and updating them accordingly so requests can remain as fast as possible.

This package will initially call `cluster slots` in order to retrieve an initial idea of the topology of the cluster, but other than that will not make any other extraneous calls.

All methods on a Cluster are thread-safe, and connections are automatically pooled

Index

• Variables
• func CRC16(buf []byte) uint16
• type Cluster
  • func NewCluster(addr string) (*Cluster, error)
  • func NewClusterTimeout(addr string, timeout time.Duration) (*Cluster, error)
  • func NewClusterWithOpts(o Opts) (*Cluster, error)
  • func (c *Cluster) ClientForKey(key string) (*redis.Client, string, error)
  • func (c *Cluster) Close()
  • func (c *Cluster) Cmd(cmd string, args ...interface{}) *redis.Reply
  • func (c *Cluster) Reset() error
• type Opts

Variables

var (
	// BadCmdNoKey is an error reply returned when no key is given to the Cmd
	// method
	BadCmdNoKey = &redis.CmdError{errors.New("bad command, no key")}
)

Functions

func CRC16

func CRC16(buf []byte) uint16

CRC16 returns checksum for a given set of bytes based on the crc algorithm defined for hashing redis keys in a cluster setup

Types

type Cluster

type Cluster struct {

	// Number of slot misses. This is incremented everytime a command's reply is
	// a MOVED or ASK message. This should be accessed in a thread-safe manner,
	// i.e. when no other routines can be calling any methods on this Cluster
	Misses uint64
	// contains filtered or unexported fields
}

Cluster wraps a Client and accounts for all redis cluster logic

func NewCluster

func NewCluster(addr string) (*Cluster, error)

NewCluster will perform the following steps to initialize:

- Connect to the node given in the argument

- Use that node to call CLUSTER SLOTS. The return from this is used to build a mapping of slot number -> connection. At the same time any new connections which need to be made are created here.

- *Cluster is returned

At this point the Cluster has a complete view of the cluster's topology and can immediately start performing commands with (theoretically) zero slot misses

func NewClusterTimeout

func NewClusterTimeout(addr string, timeout time.Duration) (*Cluster, error)

NewClusterTimeout is the Same as NewCluster, but will use timeout as the read/write timeout when communicating with cluster nodes

func NewClusterWithOpts

func NewClusterWithOpts(o Opts) (*Cluster, error)

NewClusterWithOpts is the same as NewCluster, but with more fine-tuned configuration options. See ClusterOpts for more available options

func (*Cluster) ClientForKey

func (c *Cluster) ClientForKey(key string) (*redis.Client, string, error)

ClientForKey returns the Client which *ought* to handle the given key (along with the node address for that client), based on Cluster's understanding of the cluster topology at the given moment. If the slot isn't known or there is an error contacting the correct node, a random client is returned.

The client retrieved by this method cannot be returned back to the pool inside Cluster, meaning you must call Close() on it when you're done with it. Cluster will generate new connections for its pool if need be, so don't worry about not having to return it.

func (*Cluster) Close

func (c *Cluster) Close()

Close calls Close on all connected clients. Once this is called no other methods should be called on this instance of Cluster

func (*Cluster) Cmd

func (c *Cluster) Cmd(cmd string, args ...interface{}) *redis.Reply

Cmd performs the given command on the correct cluster node and gives back the command's reply. The command *must* have a key parameter (i.e. len(args) >= 1). If any MOVED or ASK errors are returned they will be transparently handled by this method. This method will also increment the Misses field on the Cluster struct whenever a redirection occurs

func (*Cluster) Reset

func (c *Cluster) Reset() error

Reset will re-retrieve the cluster topology and set up/teardown connections as necessary. It begins by calling CLUSTER SLOTS on a random known connection. The return from that is used to re-create the topology, create any missing clients, and close any clients which are no longer needed.

This call is inherently throttled, so that multiple clients can call it at the same time and it will only actually occur once (subsequent clients will have nil returned immediately).

type Opts

type Opts struct {

	// Required. The address of a single node in the cluster
	Addr string

	// Read and write timeout which should be used on individual redis clients.
	// Default is to not set the timeout and let the connection use it's default
	Timeout time.Duration

	// The size of the connection pool to use for each host. Default is 10
	PoolSize int

	// The time which must elapse between subsequent calls to create a new
	// connection pool (on a per redis instance basis) in certain circumstances.
	// The default is 500 milliseconds
	PoolThrottle time.Duration

	// The time which must elapse between subsequent calls to Reset(). The
	// default is 500 milliseconds
	ResetThrottle time.Duration
}

Opts are Options which can be passed in to NewClusterWithOpts. If any are set to their zero value the default value will be used instead