Ruby extension that wraps hiredis reply parsing code. It is targeted at speeding up parsing multi bulk replies.
This code is considered beta.
Install with Rubygems:
gem install hiredis
When you require "hiredis"
, redis-rb will be automatically loaded and setup
to use hiredis for its connection handling.
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.
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"]
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)
This code is released under the BSD license, after the license of hiredis.