Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Ruby wrapper for hiredis
Ruby C

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
benchmark
examples
ext/hiredis_ext
lib
test
vendor
.gitignore
.gitmodules
CHANGELOG.md
COPYING
README.md
Rakefile
hiredis.gemspec

README.md

hiredis-rb

Ruby extension that wraps hiredis reply parsing code. It is targeted at speeding 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 (unreleased at the time of writing).

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 line:

gem "hiredis", "~> 0.3.0"

Until redis-rb 2.2 is released, you need to depend on this version of redis-rb for for hiredis to be automatically picked up:

gem "redis", :git => "git://github.com/ezmobius/redis-rb.git", :ref => "aa3951"

You can use Redis normally, as you would with the pure Ruby version.

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::* 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:

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

Something went wrong with that request. Please try again.