soveran/hiredis-rb

Ruby C extension that wraps hiredis reply parsing code

hiredis-rb

Ruby extension that wraps hiredis reply parsing code. It is targeted at speeding up parsing multi bulk replies.

WARNING

This code is considered beta.

Install

Install with Rubygems:

gem install hiredis

Usage

When you require "hiredis", redis-rb will be automatically loaded and setup to use hiredis for its connection handling.

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::* errors will be raised. All other errors (such as a protocol error) result in a RuntimeError.

You can stop hiredis from requiring redis-rb by simply requiring hiredis/connection. This only loads the connection class and skips loading redis-rb.

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 stop hiredis from requiring redis-rb by simply requiring hiredis/reader. This only loads the reader class and skips loading redis-rb.

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:

> reader = Hiredis::Reader.new
> reader.feed("*2\r\n$7\r\nawesome\r\n$5\r\narray\r\n")
> reader.gets
=> ["awesome", "array"]

Benchmarks

These numbers were generated by running benchmark/throughput.rb against ruby 1.8.7 (2010-08-16 patchlevel 302) [i686-darwin10.4.0]. The benchmark compares redis-rb using the Ruby socket implementation and Ruby reply parser against hiredis with C code for both 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.

                                                        user     system      total        real
redis-rb:  1x PING pipeline, 10000 times            0.320000   0.160000   0.480000 (  0.709805)
 hiredis:  1x PING pipeline, 10000 times            0.210000   0.140000   0.350000 (  0.634882)
redis-rb: 10x PING pipeline, 10000 times            1.760000   0.980000   2.740000 (  2.743499)
 hiredis: 10x PING pipeline, 10000 times            0.390000   0.120000   0.510000 (  0.866903)
redis-rb:  1x SET pipeline, 10000 times             0.350000   0.160000   0.510000 (  0.775627)
 hiredis:  1x SET pipeline, 10000 times             0.190000   0.130000   0.320000 (  0.615606)
redis-rb: 10x SET pipeline, 10000 times             2.240000   0.920000   3.160000 (  3.166384)
 hiredis: 10x SET pipeline, 10000 times             0.430000   0.140000   0.570000 (  1.040938)
redis-rb:  1x GET pipeline, 10000 times             0.360000   0.160000   0.520000 (  0.758718)
 hiredis:  1x GET pipeline, 10000 times             0.200000   0.130000   0.330000 (  0.624058)
redis-rb: 10x GET pipeline, 10000 times             2.150000   0.920000   3.070000 (  3.074284)
 hiredis: 10x GET pipeline, 10000 times             0.410000   0.130000   0.540000 (  0.954633)
redis-rb:  1x MGET(10) pipeline, 1000 times         0.110000   0.020000   0.130000 (  0.155790)
 hiredis:  1x MGET(10) pipeline, 1000 times         0.020000   0.010000   0.030000 (  0.075833)
redis-rb: 10x MGET(10) pipeline, 1000 times         0.980000   0.110000   1.090000 (  1.098079)
 hiredis: 10x MGET(10) pipeline, 1000 times         0.110000   0.010000   0.120000 (  0.213006)

License

This code is released under the BSD license, after the license of hiredis.