Documentation

Overview

Package redis is a simple client for connecting and interacting with a single redis instance.

THE FUNCTIONALITY PROVIDED IN THIS PACKAGE IS NOT THREAD-SAFE. To use a single redis instance amongst multiple go-routines, check out the pool subpackage (http://godoc.org/github.com/mediocregopher/radix.v2/pool)

To import inside your package do:

import "github.com/mediocregopher/radix.v2/redis"

Connecting

Use either Dial or DialTimeout:

client, err := redis.Dial("tcp", "localhost:6379")
if err != nil {
	// handle err
}

Make sure to call Close on the client if you want to clean it up before the end of the program.

Cmd and Resp

The Cmd method returns a Resp, which has methods for converting to various types. Each of these methods returns an error which can either be a connection error (e.g. timeout), an application error (e.g. key is wrong type), or a conversion error (e.g. cannot convert to integer). You can also directly check the error using the Err field:

foo, err := client.Cmd("GET", "foo").Str()
if err != nil {
	// handle err
}

// Checking Err field directly

err = client.Cmd("SET", "foo", "bar", "EX", 3600).Err
if err != nil {
	// handle err
}

Array Replies

The elements to Array replies can be accessed as strings using List or ListBytes, or you can use the Array method for more low level access:

r := client.Cmd("MGET", "foo", "bar", "baz")
if r.Err != nil {
	// handle error
}

// This:
l, _ := r.List()
for _, elemStr := range l {
	fmt.Println(elemStr)
}

// is equivalent to this:
elems, err := r.Array()
for i := range elems {
	elemStr, _ := elems[i].Str()
	fmt.Println(elemStr)
}

Pipelining

Pipelining is when the client sends a bunch of commands to the server at once, and only once all the commands have been sent does it start reading the replies off the socket. This is supported using the PipeAppend and PipeResp methods. PipeAppend will simply append the command to a buffer without sending it, the first time PipeResp is called it will send all the commands in the buffer and return the Resp for the first command that was sent. Subsequent calls to PipeResp return Resps for subsequent commands:

client.PipeAppend("GET", "foo")
client.PipeAppend("SET", "bar", "foo")
client.PipeAppend("DEL", "baz")

// Read GET foo reply
foo, err := client.PipeResp().Str()
if err != nil {
	// handle err
}

// Read SET bar foo reply
if err := client.PipeResp().Err; err != nil {
	// handle err
}

// Read DEL baz reply
if err := client.PipeResp().Err; err != nil {
	// handle err
}

Flattening

Radix will automatically flatten passed in maps and slices into the argument list. For example, the following are all equivalent:

client.Cmd("HMSET", "myhash", "key1", "val1", "key2", "val2")
client.Cmd("HMSET", "myhash", []string{"key1", "val1", "key2", "val2"})
client.Cmd("HMSET", "myhash", map[string]string{
	"key1": "val1",
	"key2": "val2",
})
client.Cmd("HMSET", "myhash", [][]string{
	[]string{"key1", "val1"},
	[]string{"key2", "val2"},
})

Radix is not picky about the types inside or outside the maps/slices, if they don't match a subset of primitive types it will fall back to reflection to figure out what they are and encode them.

Index

Constants

This section is empty.

Variables

View Source
var ErrPipelineEmpty = errors.New("pipeline queue empty")

    ErrPipelineEmpty is returned from PipeResp() to indicate that all commands which were put into the pipeline have had their responses read

    View Source
    var (
    
    	// ErrRespNil is returned from methods on Resp like Str, Int, etc... when
    	// called on a Resp which is a nil response
    	ErrRespNil = errors.New("response is nil")
    )

      Parse errors

      Functions

      func IsTimeout

      func IsTimeout(r *Resp) bool

        IsTimeout is a helper function for determining if an IOErr Resp was caused by a network timeout

        func KeyFromArgs

        func KeyFromArgs(args ...interface{}) (string, error)

          KeyFromArgs is a helper function which other library packages which wrap this one might find useful. It takes in a set of arguments which might be passed into Cmd and returns the first key for the command. Since radix supports complicated arguments (like slices, slices of slices, maps, etc...) this is not always as straightforward as it might seem, so this helper function is provided.

          An error is returned if no key can be determined

          Types

          type Client

          type Client struct {
          
          	// The network/address of the redis instance this client is connected to.
          	// These will be whatever strings were passed into the Dial function when
          	// creating this connection
          	Network, Addr string
          
          	// These define the max time to spend blocking on read/write connections
          	// during commands. These should not be set to zero if they were ever not
          	// zero. These may be set after the Client is initialized, but not while any
          	// methods are being called. DialTimeout will set both of these to its
          	// passed in value.
          	ReadTimeout, WriteTimeout time.Duration
          
          	// The most recent network error which occurred when either reading
          	// or writing. A critical network error is basically any non-application
          	// level error, e.g. a timeout, disconnect, etc... Close is automatically
          	// called on the client when it encounters a critical network error
          	//
          	// NOTE: The ReadResp method does *not* consider a timeout to be a critical
          	// network error, and will not set this field in the event of one. Other
          	// methods which deal with a command-then-response (e.g. Cmd, PipeResp) do
          	// set this and close the connection in the event of a timeout
          	LastCritical error
          	// contains filtered or unexported fields
          }

            Client describes a Redis client.

            func Dial

            func Dial(network, addr string) (*Client, error)

              Dial connects to the given Redis server.

              func DialTimeout

              func DialTimeout(network, addr string, timeout time.Duration) (*Client, error)

                DialTimeout connects to the given Redis server with the given timeout, which will be used as the read/write timeout when communicating with redis

                func NewClient

                func NewClient(conn net.Conn) (*Client, error)

                  NewClient initializes a Client instance with a preexisting net.Conn.

                  For example, it can be used to open SSL connections to Redis servers:

                  conn, err := tls.Dial("tcp", addr, &tls.Config{})
                  client, err := radix.NewClient(conn)
                  

                  func (*Client) Close

                  func (c *Client) Close() error

                    Close closes the connection.

                    func (*Client) Cmd

                    func (c *Client) Cmd(cmd string, args ...interface{}) *Resp

                      Cmd calls the given Redis command.

                      func (*Client) PipeAppend

                      func (c *Client) PipeAppend(cmd string, args ...interface{})

                        PipeAppend adds the given call to the pipeline queue. Use PipeResp() to read the response.

                        func (*Client) PipeClear

                        func (c *Client) PipeClear() (int, int)

                          PipeClear clears the contents of the current pipeline queue, both commands queued by PipeAppend which have yet to be sent and responses which have yet to be retrieved through PipeResp. The first returned int will be the number of pending commands dropped, the second will be the number of pending responses dropped

                          func (*Client) PipeResp

                          func (c *Client) PipeResp() *Resp

                            PipeResp returns the reply for the next request in the pipeline queue. Err with ErrPipelineEmpty is returned if the pipeline queue is empty.

                            func (*Client) ReadResp

                            func (c *Client) ReadResp() *Resp

                              ReadResp will read a Resp off of the connection without sending anything first (useful after you've sent a SUSBSCRIBE command). This will block until a reply is received or the timeout is reached (returning the IOErr). You can use IsTimeout to check if the Resp is due to a Timeout

                              Note: this is a more low-level function, you really shouldn't have to actually use it unless you're writing your own pub/sub code

                              type Resp

                              type Resp struct {
                              
                              	// Err indicates that this Resp signals some kind of error, either on the
                              	// connection level or the application level. Use IsType if you need to
                              	// determine which, otherwise you can simply check if this is nil
                              	Err error
                              	// contains filtered or unexported fields
                              }

                                Resp represents a single response or message being sent to/from a redis server. Each Resp has a type (see RespType and IsType) and a value. Values can be retrieved using any of the casting methods on this type (e.g. Str)

                                func NewResp

                                func NewResp(v interface{}) *Resp

                                  NewResp takes the given value and interprets it into a resp encoded byte stream

                                  func NewRespFlattenedStrings

                                  func NewRespFlattenedStrings(v interface{}) *Resp

                                    NewRespFlattenedStrings is like NewResp except it looks through the given value and converts any types (except slices/maps) into strings, and flatten any embedded slices/maps into a single slice. This is useful because commands to a redis server must be given as an array of bulk strings. If the argument isn't already in a slice/map it will be wrapped so that it is written as a Array of size one

                                    func NewRespIOErr

                                    func NewRespIOErr(err error) *Resp

                                      NewRespIOErr takes an error and creates an IOErr response. Use NewResp instead to create an AppErr response.

                                      func NewRespSimple

                                      func NewRespSimple(s string) *Resp

                                        NewRespSimple is like NewResp except it encodes its string as a resp SimpleStr type, whereas NewResp will encode all strings as BulkStr

                                        func (*Resp) Array

                                        func (r *Resp) Array() ([]*Resp, error)

                                          Array returns the Resp slice encompassed by this Resp. Only valid for a Resp of type Array. If r.Err != nil that will be returned

                                          func (*Resp) Bytes

                                          func (r *Resp) Bytes() ([]byte, error)

                                            Bytes returns a byte slice representing the value of the Resp. Only valid for a Resp of type Str. If r.Err != nil that will be returned.

                                            func (*Resp) Float64

                                            func (r *Resp) Float64() (float64, error)

                                              Float64 returns a float64 representing the value of the Resp. Only valud for a Resp of type Str which represents an actual float. If r.Err != nil that will be returned

                                              func (*Resp) Int

                                              func (r *Resp) Int() (int, error)

                                                Int returns an int representing the value of the Resp. For a Resp of type Int the integer value will be returned directly. For a Resp of type Str the string will attempt to be parsed as a base-10 integer, returning the parsing error if any. If r.Err != nil that will be returned

                                                func (*Resp) Int64

                                                func (r *Resp) Int64() (int64, error)

                                                  Int64 is like Int, but returns int64 instead of Int

                                                  func (*Resp) IsType

                                                  func (r *Resp) IsType(t RespType) bool

                                                    IsType returns whether or or not the reply is of a given type

                                                    isStr := r.IsType(redis.Str)
                                                    

                                                    Multiple types can be checked at the same time by or'ing the desired types

                                                    isStrOrInt := r.IsType(redis.Str | redis.Int)
                                                    

                                                    func (*Resp) List

                                                    func (r *Resp) List() ([]string, error)

                                                      List is a wrapper around Array which returns the result as a list of strings, calling Str() on each Resp which Array returns. Any errors encountered are immediately returned. Any Nil replies are interpreted as empty strings

                                                      func (*Resp) ListBytes

                                                      func (r *Resp) ListBytes() ([][]byte, error)

                                                        ListBytes is a wrapper around Array which returns the result as a list of byte slices, calling Bytes() on each Resp which Array returns. Any errors encountered are immediately returned. Any Nil replies are interpreted as nil

                                                        func (*Resp) Map

                                                        func (r *Resp) Map() (map[string]string, error)

                                                          Map is a wrapper around Array which returns the result as a map of strings, calling Str() on alternating key/values for the map. All value fields of type Nil will be treated as empty strings, keys must all be of type Str

                                                          func (*Resp) Str

                                                          func (r *Resp) Str() (string, error)

                                                            Str is a wrapper around Bytes which returns the result as a string instead of a byte slice

                                                            func (*Resp) String

                                                            func (r *Resp) String() string

                                                              String returns a string representation of the Resp. This method is for debugging, use Str() for reading a Str reply

                                                              func (*Resp) WriteTo

                                                              func (r *Resp) WriteTo(w io.Writer) (int64, error)

                                                                WriteTo writes the resp encoded form of the Resp to the given writer, implementing the WriterTo interface

                                                                type RespReader

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

                                                                  RespReader is a wrapper around an io.Reader which will read Resp messages off of the io.Reader

                                                                  func NewRespReader

                                                                  func NewRespReader(r io.Reader) *RespReader

                                                                    NewRespReader creates and returns a new RespReader which will read from the given io.Reader. Once passed in the io.Reader shouldn't be read from by any other processes

                                                                    func (*RespReader) Read

                                                                    func (rr *RespReader) Read() *Resp

                                                                      ReadResp attempts to read a message object from the given io.Reader, parse it, and return a Resp representing it

                                                                      type RespType

                                                                      type RespType int

                                                                        RespType is a field on every Resp which indicates the type of the data it contains

                                                                        const (
                                                                        	SimpleStr RespType = 1 << iota
                                                                        	BulkStr
                                                                        	IOErr  // An error which prevented reading/writing, e.g. connection close
                                                                        	AppErr // An error returned by redis, e.g. WRONGTYPE
                                                                        	Int
                                                                        	Array
                                                                        	Nil
                                                                        
                                                                        	// Str combines both SimpleStr and BulkStr, which are considered strings to
                                                                        	// the Str() method.  This is what you want to give to IsType when
                                                                        	// determining if a response is a string
                                                                        	Str = SimpleStr | BulkStr
                                                                        
                                                                        	// Err combines both IOErr and AppErr, which both indicate that the Err
                                                                        	// field on their Resp is filled. To determine if a Resp is an error you'll
                                                                        	// most often want to simply check if the Err field on it is nil
                                                                        	Err = IOErr | AppErr
                                                                        )

                                                                          Different RespTypes. You can check if a message is of one or more types using the IsType method on Resp