README.md

hiredis-rb

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.

Install

Install with Rubygems:

gem install hiredis

Usage

Hiredis can be used as standalone library, or be used together with redis-rb.
The latter adds in support for hiredis in 2.2.

redis-rb

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"
gem "redis", ">= 3.2.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:

Standalone: Connection

A connection to Redis can be opened by creating an instance of
Hiredis::Connection and calling #connect:

conn =Hiredis::Connection.new
conn.connect("127.0.0.1", 6379)

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"]
conn.write ["GET", "speed"]

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).

>> conn.read
=> "OK">> conn.read
=> "awesome"

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 RuntimeError.

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.

Use #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:

Benchmarks

These numbers were generated by running benchmark/throughput.rb against
ruby 1.9.2p180 (2011-02-18 revision 30909) [x86_64-darwin10.6.0]. The
benchmark compares redis-rb with the Ruby connection and protocol code against
redis-rb with hiredis to handle I/O and reply parsing.

For simple line or bulk replies, the throughput improvement is insignificant,
while the larger multi bulk responses will have a noticeable higher throughput.