Ruby extension that wraps hiredis. Both the synchronous connection API and a separate protocol reader are supported. It is primarily intended to speed up parsing multi bulk replies.
Hiredis is a minimalistic C client library for the Redis database.
It is minimalistic because it just adds minimal support for the protocol, but at the same time it uses a high level printf-alike API in order to make it much higher level than otherwise suggested by its minimal code base and the lack of explicit bindings for every Redis command.
Apart from supporting sending commands and receiving replies, it comes with a reply parser that is decoupled from the I/O layer. It is a stream parser designed for easy reusability, which can for instance be used in higher level language bindings for efficient reply parsing.
Hiredis only supports the binary-safe Redis protocol, so you can use it with any Redis version >= 1.2.0.
The library comes with multiple APIs. There is the synchronous API, the asynchronous API and the reply parsing API.
You can install it as a gem:
gem install hiredis
or add it into a Gemfile (Bundler):
Hiredis can be used as standalone library, or be used together with
redis-rb. The latter adds in support for hiredis in 2.2.
To use hiredis from redis-rb, it needs to be available in Ruby’s load path. Using Bundler, this comes down to adding the following lines:
gem "hiredis", "~> 0.6.0"
To use hiredis with redis-rb, you need to require
redis/connection/hiredis before creating a new connection. This makes sure that hiredis will be used instead of the pure Ruby connection code and protocol parser. Doing so in the Gemfile is done by adding a :require option to the line adding the redis-rb dependency:
gem "redis", ">= 3.2.0", :require => ["redis", "redis/connection/hiredis"]
You can use Redis normally, as you would with the pure Ruby version.
A connection to Redis can be opened by creating an instance of
Hiredis::Connection and calling
conn = Hiredis::Connection.new
Commands can be written to Redis by calling
#write with an array of arguments. You can call write more than once, resulting in a pipeline of commands.
conn.write ["SET", "speed", "awesome"]
After commands are written, use #read to receive the subsequent replies. Make sure not to call #read more than you have replies to read, or the connection will block indefinitely. You can use this feature to implement a subscriber (for Redis Pub/Sub).
When the connection was closed by the server, an error of the type
Hiredis::Connection::EOFError will be raised. For all I/O related errors, the Ruby built-in
Errno::XYZ errors will be raised. All other errors (such as a protocol error) result in a
You can skip loading everything and just load Hiredis::Connection by requiring hiredis/connection.
Standalone: Reply parser
Only using hiredis for the reply parser can be very useful in scenarios where the I/O is already handled by another component (such as EventMachine).
You can skip loading everything and just load
Hiredis::Reader by requiring hiredis/reader.
#feed on an instance of
Hiredis::Reader to feed the stream parser with new data. Use #read to get the parsed replies one by one:
reader = Hiredis::Reader.new