Getting started
===============

Connect to redis:

    require 'em-hiredis'
    redis = EM::Hiredis.connect

Or, connect to redis with a redis URL (for a different host, port, password, DB)

    redis = EM::Hiredis.connect("redis://:secretpassword@example.com:9000/4")

The client is a deferrable which succeeds when the underlying connection is established so you can bind to this. This isn't necessary however - any commands sent before the connection is established (or while reconnecting) will be sent to redis on connect.

    redis.callback { puts "Redis now connected" }

All redis commands are available without any remapping of names

    redis.set('foo', 'bar').callback {
      redis.get('foo').callback { |value|
        p [:returned, value]
      }
    }

As a shortcut, if you're only interested in binding to the success case you can simply provide a block to any command

    redis.get('foo') { |value|
      p [:returned, value]
    }

Handling failure
----------------

All commands return a deferrable. In the case that redis replies with an error (for example you called a hash operation against a set), or in the case that the redis connection is broken before the command returns, the deferrable will fail. If you care about the failure case you should bind to the errback - for example:

    redis.sadd('aset', 'member').callback {
      response_deferrable = redis.hget('aset', 'member')
      response_deferrable.errback { |e|
        p e # => #<RuntimeError: ERR Operation against a key holding the wrong kind of value>
      }
    }

Pubsub
------

This example should explain things. Once a redis connection is in a pubsub state, you must make sure you only send pubsub commands.

    redis = EM::Hiredis.connect
    subscriber = EM::Hiredis.connect

    subscriber.subscribe('bar.0')
    subscriber.psubscribe('bar.*')

    subscriber.on(:message) { |channel, message|
      p [:message, channel, message]
    }

    subscriber.on(:pmessage) { |key, channel, message|
      p [:pmessage, key, channel, message]
    }

    EM.add_periodic_timer(1) {
      redis.publish("bar.#{rand(2)}", "hello").errback { |e|
        p [:publisherror, e]
      }
    }

Hacking
-------

Hacking on em-hiredis is pretty simple, make sure you have Bundler installed:

    gem install bundler
    bundle

In order to run the tests you need to have a local redis server running on port 6379. Run all the tests:

    # WARNING: The tests call flushdb on db 9 - this clears all keys!
    bundle exec rake 

To run an individual test:

    bundle exec rspec spec/redis_commands_spec.rb

Many thanks to the em-redis gem for getting this gem bootstrapped with some tests.