# README
Radix
Radix is a full-featured Redis client for Go. See the GoDoc for documentation and general usage examples.
This is the third revision of this project, the previous one has been deprecated but can be found here.
Features
-
Standard print-like API which supports all current and future redis commands.
-
Support for using an io.Reader as a command argument and writing responses to an io.Writer, as well as marshaling/unmarshaling command arguments from structs.
-
Connection pooling, which takes advantage of implicit pipelining to reduce system calls.
-
Helpers for EVAL, SCAN, and manual pipelining.
-
Support for pubsub, as well as persistent pubsub wherein if a connection is lost a new one transparently replaces it.
-
Nearly all important types are interfaces, allowing for custom implementations of nearly anything.
Installation and Usage
Radix always aims to support the most recent two versions of go, and is likely to support others prior to those two.
Module-aware mode:
go get github.com/mediocregopher/radix/v3
// import github.com/mediocregopher/radix/v3
Legacy GOPATH mode:
go get github.com/mediocregopher/radix
// import github.com/mediocregopher/radix
Testing
# requires a redis server running on 127.0.0.1:6379
go test github.com/mediocregopher/radix/v3
Benchmarks
Thanks to a huge amount of work put in by @nussjustin, and inspiration from the redispipe project and @funny-falcon, radix/v3 is significantly faster than most redis drivers, including redigo, for normal parallel workloads, and is pretty comparable for serial workloads.
Benchmarks can be run from the bench folder. The following results were obtained
by running the benchmarks with -cpu set to 32 and 64, on a 32 core machine,
with the redis server on a separate machine. See this thread
for more details.
Some of radix's results are not included below because they use a non-default configuration.
# go get rsc.io/benchstat
# cd bench
# go test -v -run=XXX -bench=ParallelGetSet -cpu 32 -cpu 64 -benchmem . >/tmp/radix.stat
# benchstat radix.stat
name time/op
ParallelGetSet/radix/default-32 2.15µs ± 0% <--- The good stuff
ParallelGetSet/radix/default-64 2.05µs ± 0% <--- The better stuff
ParallelGetSet/redigo-32 27.9µs ± 0%
ParallelGetSet/redigo-64 28.5µs ± 0%
ParallelGetSet/redispipe-32 2.02µs ± 0%
ParallelGetSet/redispipe-64 1.71µs ± 0%
name alloc/op
ParallelGetSet/radix/default-32 72.0B ± 0%
ParallelGetSet/radix/default-64 84.0B ± 0%
ParallelGetSet/redigo-32 119B ± 0%
ParallelGetSet/redigo-64 120B ± 0%
ParallelGetSet/redispipe-32 168B ± 0%
ParallelGetSet/redispipe-64 172B ± 0%
name allocs/op
ParallelGetSet/radix/default-32 4.00 ± 0%
ParallelGetSet/radix/default-64 4.00 ± 0%
ParallelGetSet/redigo-32 6.00 ± 0%
ParallelGetSet/redigo-64 6.00 ± 0%
ParallelGetSet/redispipe-32 8.00 ± 0%
ParallelGetSet/redispipe-64 8.00 ± 0%
Copyright and licensing
Unless otherwise noted, the source files are distributed under the MIT License found in the LICENSE.txt file.
# Functions
ClusterOnDownDelayActionsBy tells the Cluster to delay all commands by the given duration while the cluster is seen to be in the CLUSTERDOWN state.
ClusterPoolFunc tells the Cluster to use the given ClientFunc when creating pools of connections to cluster members.
ClusterSlot returns the slot number the key belongs to in any redis cluster, taking into account key hash tags.
ClusterSyncEvery tells the Cluster to synchronize itself with the cluster's topology at the given interval.
ClusterWithTrace tells the Cluster to trace itself with the given ClusterTrace.
Cmd is used to perform a redis command and retrieve a result.
CRC16 returns checksum for a given set of bytes based on the crc algorithm defined for hashing redis keys in a cluster setup.
Dial is a ConnFunc which creates a Conn using net.Dial and NewConn.
DialAuthPass will cause Dial to perform an AUTH command once the connection is created, using the given pass.
DialAuthUser will cause Dial to perform an AUTH command once the connection is created, using the given user and pass.
DialConnectTimeout determines the timeout value to pass into net.DialTimeout when creating the connection.
DialReadTimeout determines the deadline to set when reading from a dialed connection.
DialSelectDB will cause Dial to perform a SELECT command once the connection is created, using the given database index.
DialTimeout is the equivalent to using DialConnectTimeout, DialReadTimeout, and DialWriteTimeout all with the same value.
DialUseTLS will cause Dial to perform a TLS handshake using the provided config.
DialWriteTimeout determines the deadline to set when writing to a dialed connection.
FlatCmd is like Cmd, but the arguments can be of almost any type, and FlatCmd will automatically flatten them into a single array of strings.
NewCluster initializes and returns a Cluster instance.
NewConn takes an existing net.Conn and wraps it to support the Conn interface of this package.
NewEvalScript initializes a EvalScript instance.
NewPool creates a *Pool which will keep open at least the given number of connections to the redis instance at the given address.
NewScanner creates a new Scanner instance which will iterate over the redis instance's Client using the ScanOpts.
NewSentinel creates and returns a *Sentinel instance.
NewStreamReader returns a new StreamReader for the given client.
PersistentPubSub is deprecated in favor of PersistentPubSubWithOpts instead.
PersistentPubSubAbortAfter changes PersistentPubSub's reconnect behavior.
PersistentPubSubConnFunc causes PersistentPubSub to use the given ConnFunc when connecting to its destination.
PersistentPubSubWithOpts is like PubSub, but instead of taking in an existing Conn to wrap it will create one on the fly.
Pipeline returns an Action which first writes multiple commands to a Conn in a single write, then reads their responses in a single read.
PoolConnFunc tells the Pool to use the given ConnFunc when creating new Conns to its redis instance.
PoolOnEmptyCreateAfter effects the Pool's behavior when there are no available connections in the Pool.
PoolOnEmptyErrAfter effects the Pool's behavior when there are no available connections in the Pool.
PoolOnEmptyWait effects the Pool's behavior when there are no available connections in the Pool.
PoolOnFullBuffer effects the Pool's behavior when it is full.
PoolOnFullClose effects the Pool's behavior when it is full.
PoolPingInterval specifies the interval at which a ping event happens.
PoolPipelineConcurrency sets the maximum number of pipelines that can be executed concurrently.
PoolPipelineWindow sets the duration after which internal pipelines will be flushed and the maximum number of commands that can be pipelined before flushing.
PoolRefillInterval specifies the interval at which a refill event happens.
PoolWithTrace tells the Pool to trace itself with the given PoolTrace Note that PoolTrace will block every point that you set to trace.
PubSub wraps the given Conn so that it becomes a PubSubConn.
PubSubStub returns a (fake) Conn, much like Stub does, which pretends it is a Conn to a real redis instance, but is instead using the given callback to service requests.
SentinelConnFunc tells the Sentinel to use the given ConnFunc when connecting to sentinel instances.
SentinelPoolFunc tells the Sentinel to use the given ClientFunc when creating a pool of connections to the sentinel's primary.
Stub returns a (fake) Conn which pretends it is a Conn to a real redis instance, but is instead using the given callback to service requests.
WithConn is used to perform a set of independent Actions on the same Conn.
# Variables
DefaultClientFunc is a ClientFunc which will return a Client for a redis instance using sane defaults.
DefaultClusterConnFunc is a ConnFunc which will return a Conn for a node in a redis cluster using sane defaults and which has READONLY mode enabled, allowing read-only commands on the connection even if the connected instance is currently a replica, either by explicitly sending commands on the connection or by using the DoSecondary method on the Cluster that owns the connection.
DefaultConnFunc is a ConnFunc which will return a Conn for a redis instance using sane defaults.
ErrPoolEmpty is used by Pools created using the PoolOnEmptyErrAfter option.
ScanAllKeys is a shortcut ScanOpts which can be used to scan all keys.
# Structs
Cluster contains all information about a redis cluster needed to interact with it, including a set of pools to each of its instances.
ClusterNode describes a single node in the cluster at a moment in time.
EvalScript contains the body of a script to be used with redis' EVAL functionality.
MaybeNil is a type which wraps a receiver.
Pool is a dynamic connection pool which implements the Client interface.
PubSubMessage describes a message being published to a subscribed channel.
ScanOpts are various parameters which can be passed into ScanWithOpts.
Sentinel is a Client which, in the background, connects to an available sentinel node and handles all of the following:
* Creates a pool to the current primary instance, as advertised by the sentinel
* Listens for events indicating the primary has changed, and automatically creates a new Client to the new primary
* Keeps track of other sentinels in the cluster, and uses them if the currently connected one becomes unreachable
.
StreamEntry is an entry in a Redis stream as returned by XRANGE, XREAD and XREADGROUP.
StreamEntryID represents an ID used in a Redis stream with the format <time>-<seq>.
StreamReaderOpts contains various options given for NewStreamReader that influence the behaviour.
# Interfaces
Action performs a task using a Conn.
Client describes an entity which can carry out Actions, e.g.
ClusterCanRetryAction is an Action which is aware of Cluster's retry behavior in the event of a slot migration.
CmdAction is a sub-class of Action which can be used in two different ways.
Conn is a Client wrapping a single network connection which synchronously reads/writes data using the redis resp protocol.
PubSubConn wraps an existing Conn to support redis' pubsub system.
Scanner is used to iterate through the results of a SCAN call (or HSCAN, SSCAN, etc...)
Once created, repeatedly call Next() on it to fill the passed in string pointer with the next result.
StreamReader allows reading from on or more streams, always returning newer entries.
# Type aliases
ClientFunc is a function which can be used to create a Client for a single redis instance on the given network/address.
ClusterOpt is an optional behavior which can be applied to the NewCluster function to effect a Cluster's behavior.
ClusterTopo describes the cluster topology at a given moment.
ConnFunc is a function which returns an initialized, ready-to-be-used Conn.
DialOpt is an optional behavior which can be applied to the Dial function to effect its behavior, or the behavior of the Conn it creates.
PersistentPubSubOpt is an optional parameter which can be passed into PersistentPubSub in order to affect its behavior.
PoolOpt is an optional behavior which can be applied to the NewPool function to effect a Pool's behavior.
SentinelOpt is an optional behavior which can be applied to the NewSentinel function to effect a Sentinel's behavior.