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 ¶
- Variables
- func IsTimeout(r *Resp) bool
- func KeyFromArgs(args ...interface{}) (string, error)
- type Client
- type Resp
- func (r *Resp) Array() ([]*Resp, error)
- func (r *Resp) Bytes() ([]byte, error)
- func (r *Resp) Float64() (float64, error)
- func (r *Resp) Int() (int, error)
- func (r *Resp) Int64() (int64, error)
- func (r *Resp) IsType(t RespType) bool
- func (r *Resp) List() ([]string, error)
- func (r *Resp) ListBytes() ([][]byte, error)
- func (r *Resp) Map() (map[string]string, error)
- func (r *Resp) Str() (string, error)
- func (r *Resp) String() string
- func (r *Resp) WriteTo(w io.Writer) (int64, error)
- type RespReader
- type RespType
Constants ¶
This section is empty.
Variables ¶
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
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 ¶
IsTimeout is a helper function for determining if an IOErr Resp was caused by a network timeout
func KeyFromArgs ¶
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 DialTimeout ¶
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 ¶
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) PipeAppend ¶
PipeAppend adds the given call to the pipeline queue. Use PipeResp() to read the response.
func (*Client) PipeClear ¶
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 ¶
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 ¶
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 ¶
NewRespIOErr takes an error and creates an IOErr response. Use NewResp instead to create an AppErr response.
func NewRespSimple ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) IsType ¶
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 ¶
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 ¶
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 ¶
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 ¶
Str is a wrapper around Bytes which returns the result as a string instead of a byte slice
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
Source Files