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 ¶
- Constants
- Variables
- func CRC16(buf []byte) uint16
- func Slot(key string) uint16
- type Cluster
- func (c *Cluster) Close()
- func (c *Cluster) Cmd(cmd string, args ...interface{}) *redis.Resp
- func (c *Cluster) GetAddrForKey(key string) string
- func (c *Cluster) GetEvery() (map[string]*redis.Client, error)
- func (c *Cluster) GetEveryAvail() map[string]int
- func (c *Cluster) GetForKey(key string) (*redis.Client, error)
- func (c *Cluster) Put(conn *redis.Client)
- func (c *Cluster) Reset() error
- type DialFunc
- type Opts
Constants ¶
const NumSlots = 16384
NumSlots is the number of slots keys are sharded into in a redis cluster
Variables ¶
var ( // ErrBadCmdNoKey is an error reply returned when no key is given to the Cmd // method ErrBadCmdNoKey = errors.New("bad command, no key") )
Functions ¶
Types ¶
type Cluster ¶
type Cluster struct { // This is written to whenever a slot miss (either a MOVED or ASK) is // encountered. This is mainly for informational purposes, it's not meant to // be actionable. If nothing is listening the message is dropped MissCh chan struct{} // This is written to whenever the cluster discovers there's been some kind // of re-ordering/addition/removal of cluster nodes. If nothing is listening // the message is dropped ChangeCh chan struct{} // contains filtered or unexported fields }
Cluster wraps a Client and accounts for all redis cluster logic
func New ¶
New 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 NewWithOpts ¶
NewWithOpts is the same as NewCluster, but with more fine-tuned configuration options. See Opts for more available options
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 ¶
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.
NOTE if you're doing any lua or scan operations through this method you might save yourself some time and effort by checking out the LuaEval and NewScanner functions in the util package. They properly handle the cluster client being used.
func (*Cluster) GetAddrForKey ¶
GetAddrForKey returns the address which would be used to handle the given key in the cluster.
func (*Cluster) GetEvery ¶
GetEvery returns a single *redis.Client per master that the cluster currently knows about. The map returned maps the address of the client to the client itself. If there is an error retrieving any of the clients (for instance if a new connection has to be made to get it) only that error is returned. Each client must be returned back to its pools using Put when through
func (*Cluster) GetEveryAvail ¶
GetEveryAvail returns a mapping of every master address to the results of calling Avail on that instance's Pool instance. See pool.Avail for specifics on what Avail means.
func (*Cluster) GetForKey ¶
GetForKey returns the Client which *ought* to handle the given key, 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 must be returned back to its pool using Put when through
func (*Cluster) Put ¶
Put putss the connection back in its pool. To be used alongside any of the Get* methods once use of the redis.Client is done
func (*Cluster) Reset ¶
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 DialFunc ¶
DialFunc is a function which can be incorporated into Opts. Note that network will always be "tcp" in Cluster.
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. This will be ignored if the Dialer field is set. 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 // The function which will be used to create connections within the pool for // each redis cluster instance. The common use-case is to do authentication // for new connections. Defaults to using redis.DialTimeout if not set. Dialer DialFunc }
Opts are Options which can be passed in to NewWithOpts. If any are set to their zero value the default value will be used instead