redis 3.0.0.rc1 → 3.0.0.rc2

data/.travis.yml

@@ -0,0 +1,50 @@
+language: ruby
+
+branches:
+  only:
+    - master
+    - test-unit
+
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode
+  - jruby-19mode
+
+gemfile:
+  - .travis/Gemfile
+
+env:
+  - conn=ruby
+  - conn=hiredis
+  - conn=synchrony
+
+matrix:
+  exclude:
+    # hiredis
+    - rvm: jruby-18mode
+      gemfile: .travis/Gemfile
+      env: conn=hiredis
+    - rvm: jruby-19mode
+      gemfile: .travis/Gemfile
+      env: conn=hiredis
+
+    # synchrony
+    - rvm: 1.8.7
+      gemfile: .travis/Gemfile
+      env: conn=synchrony
+    - rvm: jruby-18mode
+      gemfile: .travis/Gemfile
+      env: conn=synchrony
+    - rvm: jruby-19mode
+      gemfile: .travis/Gemfile
+      env: conn=synchrony
+
+notifications:
+  irc:
+    - irc.freenode.net#redis-rb
+  email:
+    - damian.janowski@gmail.com
+    - michel@soveran.com
+    - pcnoordhuis@gmail.com

data/.travis/Gemfile

@@ -0,0 +1,11 @@
+source "https://rubygems.org"
+
+gemspec :path => "../"
+
+case ENV["conn"]
+when "hiredis"
+  gem "hiredis"
+when "synchrony"
+  gem "hiredis"
+  gem "em-synchrony"
+end

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 3.0 (unreleased)
 
+* The repository now lives at [https://github.com/redis/redis-rb](https://github.com/redis/redis-rb).
+  Thanks, Ezra!
+
+* Added support for `PEXPIRE`, `PTTL`, `PEXPIREAT`, `PSETEX`,
+  `INCRYBYFLOAT`, `HINCRYBYFLOAT` and `TIME` (Redis 2.6).
+
+* `Redis.current` is now thread unsafe, because the client itself is thread safe.
+
+    In the future you'll be able to do something like:
+
+        Redis.current = Redis::Pool.connect
+
+    This makes `Redis.current` actually usable in multi-threaded environments,
+    while not affecting those running a single thread.
+
+* Change API for `BLPOP`, `BRPOP` and `BRPOPLPUSH`. Both `BLPOP` and
+  `BRPOP` now take a single argument equal to a string key, or an array
+  with string keys, followed by an optional hash with a `:timeout` key.
+  `BRPOPLPUSH` also takes an optional hash with a `:timeout` key as last
+  argument for consistency. By default, these commands use a timeout of
+  `0` to not time out.
+
+* When `SORT` is passed multiple key patterns to get via the `:get`
+  option, it now returns an array per result element, holding all `GET`
+  substitutions.
+
+* The `MSETNX` command now returns a boolean.
+
 * The `ZRANGE`, `ZREVRANGE`, `ZRANGEBYSCORE` and `ZREVRANGEBYSCORE` commands
   now return an array containing `[String, Float]` pairs when
   `:with_scores => true` is passed.
@@ -9,34 +37,34 @@
 
 * The client now raises custom exceptions where it makes sense.
 
-  If by any chance you were rescuing low-level exceptions (`Errno::*`),
-  you should now rescue as follows:
+    If by any chance you were rescuing low-level exceptions (`Errno::*`),
+    you should now rescue as follows:
 
-      Errno::ECONNRESET    -> Redis::ConnectionError
-      Errno::EPIPE         -> Redis::ConnectionError
-      Errno::ECONNABORTED  -> Redis::ConnectionError
-      Errno::EBADF         -> Redis::ConnectionError
-      Errno::EINVAL        -> Redis::ConnectionError
-      Errno::EAGAIN        -> Redis::TimeoutError
-      Errno::ECONNREFUSED  -> Redis::CannotConnectError
+        Errno::ECONNRESET    -> Redis::ConnectionError
+        Errno::EPIPE         -> Redis::ConnectionError
+        Errno::ECONNABORTED  -> Redis::ConnectionError
+        Errno::EBADF         -> Redis::ConnectionError
+        Errno::EINVAL        -> Redis::ConnectionError
+        Errno::EAGAIN        -> Redis::TimeoutError
+        Errno::ECONNREFUSED  -> Redis::CannotConnectError
 
 * Always raise exceptions originating from erroneous command invocation
   inside pipelines and MULTI/EXEC blocks.
 
-  The old behavior (swallowing exceptions) could cause application bugs
-  to go unnoticed.
+    The old behavior (swallowing exceptions) could cause application bugs
+    to go unnoticed.
 
 * Implement futures for assigning values inside pipelines and MULTI/EXEC
   blocks. Futures are assigned their value after the pipeline or
   MULTI/EXEC block has executed.
 
-```ruby
-$redis.pipelined do
-  @future = $redis.get "key"
-end
+    ```ruby
+    $redis.pipelined do
+      @future = $redis.get "key"
+    end
 
-puts @future.value
-```
+    puts @future.value
+    ```
 
 * Ruby 1.8.6 is officially not supported.
 
@@ -45,7 +73,7 @@ puts @future.value
 * Pipelined commands now return the same replies as when called outside
   a pipeline.
 
-  In the past, pipelined replies were returned without post-processing.
+    In the past, pipelined replies were returned without post-processing.
 
 * Support `SLOWLOG` command (Michael Bernstein).
 
@@ -56,7 +84,7 @@ puts @future.value
 
 * Connecting using a URL now checks that a host is given.
 
-  It's just a small sanity check, cf. #126
+    It's just a small sanity check, cf. #126
 
 * Support variadic commands introduced in Redis 2.4.
 

data/README.md

@@ -1,195 +1,205 @@
-# redis-rb
+# redis-rb [![Build Status][travis-image]][travis-link]
 
-A Ruby client library for the [Redis](http://redis.io) key-value store.
+[travis-image]: https://secure.travis-ci.org/redis/redis-rb.png?branch=master
+[travis-link]: http://travis-ci.org/redis/redis-rb
+[travis-home]: http://travis-ci.org/
 
-A simple Ruby client trying to match Redis' API one-to-one while still providing a Rubystic interface.
-It features thread safety, client-side sharding, and an obsession for performance.
+A Ruby client library for [Redis][redis-home].
 
-## A note about versions
+[redis-home]: http://redis.io
 
-Versions *1.0.x* target all versions of Redis. You have to use this one if you are using Redis < 1.2.
-
-Version *2.0* is a big refactoring of the previous version and makes little effort to be
-backwards-compatible when it shouldn't. It does not support Redis' original protocol, favoring the
-new, binary-safe one. You should be using this version if you're running Redis 1.2+.
-
-## Information about Redis
-
-Redis is a key-value store with some interesting features:
-
-1. It's fast.
-2. Keys are strings but values are typed. Currently Redis supports strings, lists, sets, sorted sets and hashes. [Atomic operations](http://redis.io/commands) can be done on all of these types.
-
-See [the Redis homepage](http://redis.io) for more information.
+A Ruby client that tries to match Redis' API one-to-one, while still
+providing an idiomatic interface. It features thread-safety, client-side
+sharding, pipelining, and an obsession for performance.
 
 ## Getting started
 
-You can connect to Redis by instantiating the `Redis` class:
-
-    require "redis"
-
-    redis = Redis.new
-
-This assumes Redis was started with default values listening on `localhost`, port 6379. If you need to connect to a remote server or a different port, try:
-
-    redis = Redis.new(:host => "10.0.1.1", :port => 6380)
-
-To connect to Redis listening on a unix socket, try:
-
-    redis = Redis.new(:path => "/tmp/redis.sock")
-
-Once connected, you can start running commands against Redis:
-
-    >> redis.set "foo", "bar"
-    => "OK"
-
-    >> redis.get "foo"
-    => "bar"
-
-    >> redis.sadd "users", "albert"
-    => true
-
-    >> redis.sadd "users", "bernard"
-    => true
-
-    >> redis.sadd "users", "charles"
-    => true
-
-How many users?
-
-    >> redis.scard "users"
-    => 3
+As of version 2.0 this client only targets Redis version 2.0 and higher.
+You can use an older version of this client if you need to interface
+with a Redis instance older than 2.0, but this is no longer supported.
 
-Is `albert` a user?
-
-    >> redis.sismember "users", "albert"
-    => true
-
-Is `isabel` a user?
-
-    >> redis.sismember "users", "isabel"
-    => false
+You can connect to Redis by instantiating the `Redis` class:
 
-Handle groups:
+```ruby
+require "redis"
 
-    >> redis.sadd "admins", "albert"
-    => true
+redis = Redis.new
+```
 
-    >> redis.sadd "admins", "isabel"
-    => true
+This assumes Redis was started with a default configuration, and it
+listening on `localhost`, port 6379. If you need to connect to a remote
+server or a different port, try:
 
-Users who are also admins:
+```ruby
+redis = Redis.new(:host => "10.0.1.1", :port => 6380)
+```
 
-    >> redis.sinter "users", "admins"
-    => ["albert"]
+To connect to Redis listening on a Unix socket, try:
 
-Users who are not admins:
+```ruby
+redis = Redis.new(:path => "/tmp/redis.sock")
+```
 
-    >> redis.sdiff "users", "admins"
-    => ["bernard", "charles"]
+The Redis class exports methods that are named identical to the commands
+they execute. The arguments these methods accept are often identical to
+the arguments specified on the [Redis website][redis-commands]. For
+instance, the `SET` and `GET` commands can be called like this:
 
-Admins who are not users:
+[redis-commands]: http://redis.io/commands
 
-    >> redis.sdiff "admins", "users"
-    => ["isabel"]
+```ruby
+redis.set("mykey", "hello world")
+# => "OK"
 
-All users and admins:
+redis.get("mykey")
+# => "hello world"
+```
 
-    >> redis.sunion "admins", "users"
-    => ["albert", "bernard", "charles", "isabel"]
+All commands, their arguments and return values are documented, and
+available on [rdoc.info][rdoc].
 
+[rdoc]: http://rdoc.info/github/redis/redis-rb/
 
 ## Storing objects
 
-Redis only stores strings as values. If you want to store an object inside a key, you can use a serialization/deseralization mechanism like JSON:
-
-    >> require 'json'
-    => true
-
-    >> redis.set "foo", [1, 2, 3].to_json
-    => OK
-
-    >> JSON.parse(redis.get("foo"))
-    => [1, 2, 3]
-
-## Executing multiple commands atomically
-
-You can use `MULTI/EXEC` to run arbitrary commands in an atomic fashion:
-
-    redis.multi do
-      redis.set "foo", "bar"
-      redis.incr "baz"
-    end
-
-## Multithreaded Operation
-
-Starting with redis-rb 2.2.0, the client is thread-safe by default. To use
-earlier versions safely in a multithreaded environment, be sure to initialize
-the client with `:thread_safe => true`. Thread-safety can be explicitly
-disabled for versions 2.2 and up by initializing the client with `:thread_safe
-=> false`.
-
-See the tests and benchmarks for examples.
+Redis only stores strings as values. If you want to store an object, you
+can use a serialization mechanism such as JSON:
+
+```ruby
+require "json"
+
+redis.set "foo", [1, 2, 3].to_json
+# => OK
+
+JSON.parse(redis.get("foo"))
+# => [1, 2, 3]
+```
+
+## Pipelining
+
+When multiple commands are executed sequentially, but are not dependent,
+the calls can be *pipelined*. This means that the client doesn't wait
+for reply of the first command before sending the next command. The
+advantage is that multiple commands are sent at once, resulting in
+faster overall execution.
+
+The client can be instructed to pipeline commands by using the
+`#pipelined` method. After the block is executed, the client sends all
+commands to Redis and gathers their replies. These replies are returned
+by the `#pipelined` method.
+
+```ruby
+redis.pipelined do
+  redis.set "foo", "bar"
+  redis.incr "baz"
+end
+# => ["OK", 1]
+```
+
+### Executing commands atomically
+
+You can use `MULTI/EXEC` to run a number of commands in an atomic
+fashion. This is similar to executing a pipeline, but the commands are
+preceded by a call to `MULTI`, and followed by a call to `EXEC`. Like
+the regular pipeline, the replies to the commands are returned by the
+`#multi` method.
+
+```ruby
+redis.multi do
+  redis.set "foo", "bar"
+  redis.incr "baz"
+end
+# => ["OK", 1]
+```
+
+### Futures
+
+Replies to commands in a pipeline can be accessed via the *futures* they
+emit (since redis-rb 3.0). All calls inside a pipeline block return a
+`Future` object, which responds to the `#value` method. When the
+pipeline has succesfully executed, all futures are assigned their
+respective replies and can be used.
+
+```ruby
+redis.pipelined do
+  @set = redis.set "foo", "bar"
+  @incr = redis.incr "baz"
+end
+
+@set.value
+# => "OK"
+
+@incr.value
+# => 1
+```
 
 ## Alternate drivers
 
-Non-default connection drivers are only used when they are explicitly required.
 By default, redis-rb uses Ruby's socket library to talk with Redis.
+To use an alternative connection driver it should be specified as option
+when instantiating the client object. These instructions are only valid
+for **redis-rb 3.0**. For instructions on how to use alternate drivers from
+**redis-rb 2.2**, please refer to an [older README][readme-2.2.2].
+
+[readme-2.2.2]: https://github.com/redis/redis-rb/blob/v2.2.2/README.md
 
 ### hiredis
 
-Using redis-rb with hiredis-rb (v0.3 or higher) as backend is done by requiring
-`redis/connection/hiredis` before requiring `redis`. This will make redis-rb
-pick up hiredis as default driver automatically. This driver optimizes for
-speed, at the cost of portability. Since hiredis is a C extension, JRuby is not
-supported (by default). Use hiredis when you have large array replies (think
-`LRANGE`, `SMEMBERS`, `ZRANGE`, etc.) and/or large pipelines of commands.
+The hiredis driver uses the connection facility of hiredis-rb. In turn,
+hiredis-rb is a binding to the official hiredis client library. It
+optimizes for speed, at the cost of portability. Because it is a C
+extension, JRuby is not supported (by default).
 
-Using redis-rb with hiredis from a Gemfile:
+It is best to use hiredis when you have large replies (for example:
+`LRANGE`, `SMEMBERS`, `ZRANGE`, etc.) and/or use big pipelines.
 
-    gem "hiredis", "~> 0.3.1"
-    gem "redis", "~> 2.2.0", :require => ["redis/connection/hiredis", "redis"]
+In your Gemfile, include hiredis:
 
-### synchrony
+```ruby
+gem "redis", "~> 3.0.0.rc2"
+gem "hiredis", "~> 0.4.5"
+```
 
-This driver adds support for
-[em-synchrony](https://github.com/igrigorik/em-synchrony). Using the synchrony
-backend from redis-rb is done by requiring `redis/connection/synchrony` before
-requiring `redis`. This driver makes redis-rb work with EventMachine's
-asynchronous I/O, while not changing the exposed API. The hiredis gem needs to
-be available as well, because the synchrony driver uses hiredis for parsing the
-Redis protocol.
+When instantiating the client object, specify hiredis:
 
-Using redis-rb with synchrony from a Gemfile:
+```ruby
+redis = Redis.new(:driver => :hiredis)
+```
 
-    gem "hiredis", "~> 0.3.1"
-    gem "em-synchrony"
-    gem "redis", "~> 2.2.0", :require => ["redis/connection/synchrony", "redis"]
+### synchrony
 
-## Testing
+The synchrony driver adds support for [em-synchrony][em-synchrony].
+This makes redis-rb work with EventMachine's asynchronous I/O, while not
+changing the exposed API. The hiredis gem needs to be available as
+well, because the synchrony driver uses hiredis for parsing the Redis
+protocol.
 
-This library (v2.2) is tested against the following interpreters:
+[em-synchrony]: https://github.com/igrigorik/em-synchrony
 
-* MRI 1.8.7 (drivers: Ruby, hiredis)
-* MRI 1.9.2 (drivers: Ruby, hiredis, em-synchrony)
-* JRuby 1.6 (drivers: Ruby)
-* Rubinius 1.2 (drivers: Ruby, hiredis)
+In your Gemfile, include em-synchrony and hiredis:
 
-## Known issues
+```ruby
+gem "redis", "~> 3.0.0.rc2"
+gem "hiredis", "~> 0.4.5"
+gem "em-synchrony"
+```
 
-* Ruby 1.9 doesn't raise on socket timeouts in `IO#read` but rather retries the
-  read operation. This means socket timeouts don't work on 1.9 when using the
-  pure Ruby I/O code. Use hiredis when you want use socket timeouts on 1.9.
+When instantiating the client object, specify hiredis:
 
-* Ruby 1.8 *does* raise on socket timeouts in `IO#read`, but prints a warning
-  that using `IO#read` for non blocking reads is obsolete. This is wrong, since
-  the read is in fact blocking, but `EAGAIN` (which is returned on socket
-  timeouts) is interpreted as if the read was non blocking. Use hiredis to
-  prevent seeing this warning.
+```ruby
+redis = Redis.new(:driver => :synchrony)
+```
+
+## Testing
 
-## More info
+This library is tested using [Travis][travis-home], where it is tested
+against the following interpreters and drivers:
 
-Check the [Redis Command Reference](http://redis.io/commands) or check the tests to find out how to use this client.
+* MRI 1.8.7 (drivers: ruby, hiredis)
+* MRI 1.9.2 (drivers: ruby, hiredis, synchrony)
+* MRI 1.9.3 (drivers: ruby, hiredis, synchrony)
+* JRuby 1.6 (1.8 mode) (drivers: ruby)
+* JRuby 1.6 (1.9 mode) (drivers: ruby)
 
 ## Contributors
 
@@ -211,4 +221,5 @@ all contributors)
 
 ## Contributing
 
-[Fork the project](http://github.com/ezmobius/redis-rb) and send pull requests. You can also ask for help at `#redis-rb` on Freenode.
+[Fork the project](https://github.com/redis/redis-rb) and send pull
+requests. You can also ask for help at `#redis-rb` on Freenode.