Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/redis/hiredis-rb
Ruby wrapper for hiredis
https://github.com/redis/hiredis-rb
Last synced: about 1 month ago
JSON representation
Ruby wrapper for hiredis
- Host: GitHub
- URL: https://github.com/redis/hiredis-rb
- Owner: redis
- License: bsd-3-clause
- Created: 2010-09-21T12:42:08.000Z (almost 14 years ago)
- Default Branch: master
- Last Pushed: 2022-11-28T20:30:14.000Z (almost 2 years ago)
- Last Synced: 2024-04-14T19:56:21.870Z (5 months ago)
- Language: Ruby
- Homepage:
- Size: 217 KB
- Stars: 317
- Watchers: 20
- Forks: 89
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: COPYING
Awesome Lists containing this project
README
# hiredis-rb
[](https://github.com/redis/hiredis-rb/actions)
Ruby extension that wraps [hiredis](http://github.com/redis/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:
``` ruby
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:
``` ruby
gem "redis", ">= 3.2.0", :require => ["redis", "redis/connection/hiredis"]
```
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`:
``` ruby
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.
``` ruby
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).
``` ruby
>> 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:
``` ruby
>> 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.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.
user system total real
redis-rb: 1x SET pipeline, 10000 times 0.260000 0.140000 0.400000 ( 0.726216)
hiredis: 1x SET pipeline, 10000 times 0.170000 0.130000 0.300000 ( 0.602332)
redis-rb: 10x SET pipeline, 10000 times 1.550000 0.660000 2.210000 ( 2.231505)
hiredis: 10x SET pipeline, 10000 times 0.400000 0.140000 0.540000 ( 0.995266)
redis-rb: 1x GET pipeline, 10000 times 0.270000 0.150000 0.420000 ( 0.730322)
hiredis: 1x GET pipeline, 10000 times 0.170000 0.130000 0.300000 ( 0.604060)
redis-rb: 10x GET pipeline, 10000 times 1.480000 0.640000 2.120000 ( 2.122215)
hiredis: 10x GET pipeline, 10000 times 0.380000 0.130000 0.510000 ( 0.925731)
redis-rb: 1x LPUSH pipeline, 10000 times 0.260000 0.150000 0.410000 ( 0.725292)
hiredis: 1x LPUSH pipeline, 10000 times 0.160000 0.130000 0.290000 ( 0.592466)
redis-rb: 10x LPUSH pipeline, 10000 times 1.540000 0.660000 2.200000 ( 2.202709)
hiredis: 10x LPUSH pipeline, 10000 times 0.360000 0.130000 0.490000 ( 0.940361)
redis-rb: 1x LRANGE(100) pipeline, 1000 times 0.240000 0.020000 0.260000 ( 0.307504)
hiredis: 1x LRANGE(100) pipeline, 1000 times 0.050000 0.020000 0.070000 ( 0.100293)
redis-rb: 1x LRANGE(1000) pipeline, 1000 times 2.100000 0.030000 2.130000 ( 2.353551)
hiredis: 1x LRANGE(1000) pipeline, 1000 times 0.320000 0.030000 0.350000 ( 0.472789)
## License
This code is released under the BSD license, after the license of hiredis.