redis2-namespaced 3.0.7

data/README.md

@@ -0,0 +1,251 @@
+# redis-rb [![Build Status][travis-image]][travis-link] [![Inline docs][inchpages-image]][inchpages-link]
+
+[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/
+[inchpages-image]: http://inch-pages.github.io/github/redis/redis-rb.png
+[inchpages-link]: http://inch-pages.github.io/github/redis/redis-rb
+
+A Ruby client library for [Redis2][redis-home].
+
+[redis-home]: http://redis.io
+
+A Ruby client that tries to match Redis2' API one-to-one, while still
+providing an idiomatic interface. It features thread-safety, client-side
+sharding, pipelining, and an obsession for performance.
+
+## Upgrading from 2.x to 3.0
+
+Please refer to the [CHANGELOG][changelog-3.0.0] for a summary of the
+most important changes, as well as a full list of changes.
+
+[changelog-3.0.0]: https://github.com/redis/redis-rb/blob/master/CHANGELOG.md#300
+
+## Getting started
+
+As of version 2.0 this client only targets Redis2 version 2.0 and higher.
+You can use an older version of this client if you need to interface
+with a Redis2 instance older than 2.0, but this is no longer supported.
+
+You can connect to Redis2 by instantiating the `Redis2` class:
+
+```ruby
+require "redis"
+
+redis = Redis2.new
+```
+
+This assumes Redis2 was started with a default configuration, and is
+listening on `localhost`, port 6379. If you need to connect to a remote
+server or a different port, try:
+
+```ruby
+redis = Redis2.new(:host => "10.0.1.1", :port => 6380, :db => 15)
+```
+
+You can also specify connection options as an URL:
+
+```ruby
+redis = Redis2.new(:url => "redis://:p4ssw0rd@10.0.1.1:6380/15")
+```
+
+By default, the client will try to read the `REDIS_URL` environment variable
+and use that as URL to connect to. The above statement is therefore equivalent
+to setting this environment variable and calling `Redis2.new` without arguments.
+
+To connect to Redis2 listening on a Unix socket, try:
+
+```ruby
+redis = Redis2.new(:path => "/tmp/redis.sock")
+```
+
+To connect to a password protected Redis2 instance, use:
+
+```ruby
+redis = Redis2.new(:password => "mysecret")
+```
+
+The Redis2 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 [Redis2 website][redis-commands]. For
+instance, the `SET` and `GET` commands can be called like this:
+
+[redis-commands]: http://redis.io/commands
+
+```ruby
+redis.set("mykey", "hello world")
+# => "OK"
+
+redis.get("mykey")
+# => "hello world"
+```
+
+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
+
+Redis2 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 Redis2 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
+
+By default, redis-rb uses Ruby's socket library to talk with Redis2.
+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
+
+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).
+
+It is best to use hiredis when you have large replies (for example:
+`LRANGE`, `SMEMBERS`, `ZRANGE`, etc.) and/or use big pipelines.
+
+In your Gemfile, include hiredis:
+
+```ruby
+gem "redis", "~> 3.0.1"
+gem "hiredis", "~> 0.4.5"
+```
+
+When instantiating the client object, specify hiredis:
+
+```ruby
+redis = Redis2.new(:driver => :hiredis)
+```
+
+### synchrony
+
+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 Redis2
+protocol.
+
+[em-synchrony]: https://github.com/igrigorik/em-synchrony
+
+In your Gemfile, include em-synchrony and hiredis:
+
+```ruby
+gem "redis", "~> 3.0.1"
+gem "hiredis", "~> 0.4.5"
+gem "em-synchrony"
+```
+
+When instantiating the client object, specify synchrony:
+
+```ruby
+redis = Redis2.new(:driver => :synchrony)
+```
+
+## Testing
+
+This library is tested using [Travis][travis-home], where it is tested
+against the following interpreters and drivers:
+
+* MRI 1.8.7 (drivers: ruby, hiredis)
+* MRI 1.9.2 (drivers: ruby, hiredis, synchrony)
+* MRI 1.9.3 (drivers: ruby, hiredis, synchrony)
+* MRI 2.0.0 (drivers: ruby, hiredis, synchrony)
+* JRuby 1.7 (1.8 mode) (drivers: ruby)
+* JRuby 1.7 (1.9 mode) (drivers: ruby)
+
+## Contributors
+
+(ordered chronologically with more than 5 commits, see `git shortlog -sn` for
+all contributors)
+
+* Ezra Zygmuntowicz
+* Taylor Weibley
+* Matthew Clark
+* Brian McKinney
+* Luca Guidi
+* Salvatore Sanfillipo
+* Chris Wanstrath
+* Damian Janowski
+* Michel Martens
+* Nick Quaranto
+* Pieter Noordhuis
+* Ilya Grigorik
+
+## Contributing
+
+[Fork the project](https://github.com/redis/redis-rb) and send pull
+requests. You can also ask for help at `#redis-rb` on Freenode.

data/Rakefile

@@ -0,0 +1,403 @@
+require 'rubygems'
+require 'rubygems/package_task'
+require 'rake/testtask'
+
+ENV["REDIS_BRANCH"] ||= "unstable"
+
+$:.unshift File.join(File.dirname(__FILE__), 'lib')
+require 'redis2/version'
+
+REDIS_DIR = File.expand_path(File.join("..", "test"), __FILE__)
+REDIS_CNF = File.join(REDIS_DIR, "test.conf")
+REDIS_PID = File.join(REDIS_DIR, "db", "redis.pid")
+BINARY = "tmp/redis-#{ENV["REDIS_BRANCH"]}/src/redis-server"
+
+task :default => :run
+
+desc "Run tests and manage server start/stop"
+task :run => [:start, :test, :stop]
+
+desc "Start the Redis2 server"
+task :start => BINARY do
+  sh "#{BINARY} --version"
+
+  redis_running = \
+  begin
+    File.exists?(REDIS_PID) && Process.kill(0, File.read(REDIS_PID).to_i)
+  rescue Errno::ESRCH
+    FileUtils.rm REDIS_PID
+    false
+  end
+
+  unless redis_running
+    unless system("#{BINARY} #{REDIS_CNF}")
+      abort "could not start redis-server"
+    end
+  end
+end
+
+desc "Stop the Redis2 server"
+task :stop do
+  if File.exists?(REDIS_PID)
+    Process.kill "INT", File.read(REDIS_PID).to_i
+    FileUtils.rm REDIS_PID
+  end
+end
+
+file BINARY do
+  branch = ENV.fetch("REDIS_BRANCH")
+
+  sh <<-SH
+  mkdir -p tmp;
+  cd tmp;
+  wget https://github.com/antirez/redis/archive/#{branch}.tar.gz -O #{branch}.tar.gz;
+  tar xf #{branch}.tar.gz;
+  cd redis-#{branch};
+  make
+  SH
+end
+
+Rake::TestTask.new do |t|
+  t.options = "-v"
+  t.test_files = FileList["test/*_test.rb"]
+end
+
+task :doc => ["doc:generate", "doc:prepare"]
+
+namespace :doc do
+  task :generate do
+    require "shellwords"
+
+    `rm -rf doc`
+
+    current_branch = `git branch`[/^\* (.*)$/, 1]
+
+    begin
+      tags = `git tag -l`.split("\n").sort.reverse
+
+      tags.each do |tag|
+        `git checkout -q #{tag} 2>/dev/null`
+
+        unless $?.success?
+          $stderr.puts "Need a clean working copy. Please git-stash away."
+          exit 1
+        end
+
+        puts tag
+
+        `mkdir -p doc/#{tag}`
+
+        files = `git ls-tree -r HEAD lib`.split("\n").map do |line|
+          line[/\t(.*)$/, 1]
+        end
+
+        opts = [
+          "--title", "A Ruby client for Redis2",
+          "--output", "doc/#{tag}",
+          "--no-cache",
+          "--no-save",
+          "-q",
+          *files
+        ]
+
+        `yardoc #{Shellwords.shelljoin opts}`
+      end
+    ensure
+      `git checkout -q #{current_branch}`
+    end
+  end
+
+  task :prepare do
+    versions = `git tag -l`.split("\n").grep(/^v/).sort
+    latest_version = versions.last
+
+    File.open("doc/.htaccess", "w") do |file|
+      file.puts "RedirectMatch 302 ^/?$ /#{latest_version}"
+    end
+
+    File.open("doc/robots.txt", "w") do |file|
+      file.puts "User-Agent: *"
+
+      (versions - [latest_version]).each do |version|
+        file.puts "Disallow: /#{version}"
+      end
+    end
+
+    google_analytics = <<-EOS
+    <script type="text/javascript">
+
+      var _gaq = _gaq || [];
+      _gaq.push(['_setAccount', 'UA-11356145-2']);
+      _gaq.push(['_trackPageview']);
+
+      (function() {
+        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+      })();
+
+    </script>
+    EOS
+
+    Dir["doc/**/*.html"].each do |path|
+      lines = IO.readlines(path)
+
+      File.open(path, "w") do |file|
+        lines.each do |line|
+          if line.include?("</head>")
+            file.write(google_analytics)
+          end
+
+          file.write(line)
+        end
+      end
+    end
+  end
+
+  task :deploy do
+    system "rsync --del -avz doc/ redis-rb.keyvalue.org:deploys/redis-rb.keyvalue.org/"
+  end
+end
+
+class Source
+
+  MATCHER = "(?:\\s{%d}#[^\\n]*\\n)*^\\s{%d}def ([a-z_?]+)(?:\(.*?\))?\\n.*?^\\s{%d}end\\n\\n"
+
+  def initialize(data, options = {})
+    @doc = parse(File.read(data), options)
+  end
+
+  def methods
+    @doc.select do |d|
+      d.is_a?(Method)
+    end.map do |d|
+      d.name
+    end
+  end
+
+  def move(a, b)
+    ao = @doc.find { |m| m.is_a?(Method) && m.name == a }
+    bo = @doc.find { |m| m.is_a?(Method) && m.name == b }
+    ai = @doc.index(ao)
+    bi = @doc.index(bo)
+
+    @doc.delete_at(ai)
+    @doc.insert(bi, ao)
+
+    nil
+  end
+
+  def to_s
+    @doc.join
+  end
+
+  protected
+
+  def parse(data, options = {})
+    re = Regexp.new(MATCHER % ([options[:indent]] * 3), Regexp::MULTILINE)
+    tail = data.dup
+    doc = []
+
+    while match = re.match(tail)
+      doc << match.pre_match
+      doc << Method.new(match)
+      tail = match.post_match
+    end
+
+    doc << tail if tail
+    doc
+  end
+
+  class Method
+
+    def initialize(match)
+      @match = match
+    end
+
+    def name
+      @match[1]
+    end
+
+    def to_s
+      @match[0]
+    end
+  end
+end
+
+namespace :commands do
+  def redis_commands
+    $redis_commands ||= doc.keys.map do |key|
+      key.split(" ").first.downcase
+    end.uniq
+  end
+
+  def doc
+    $doc ||= begin
+      require "open-uri"
+      require "json"
+
+      JSON.parse(open("https://github.com/antirez/redis-doc/raw/master/commands.json").read)
+    end
+  end
+
+  task :order do
+    require "json"
+
+    reference = if File.exist?(".order")
+                  JSON.parse(File.read(".order"))
+                else
+                  {}
+                end
+
+    buckets = {}
+    doc.each do |k, v|
+      buckets[v["group"]] ||= []
+      buckets[v["group"]] << k.split.first.downcase
+      buckets[v["group"]].uniq!
+    end
+
+    result = (reference.keys + (buckets.keys - reference.keys)).map do |g|
+      [g, reference[g] + (buckets[g] - reference[g])]
+    end
+
+    File.open(".order", "w") do |f|
+      f.write(JSON.pretty_generate(Hash[result]))
+    end
+  end
+
+  def reorder(file, options = {})
+    require "json"
+    require "set"
+
+    STDERR.puts "reordering #{file}..."
+
+    reference = if File.exist?(".order")
+                  JSON.parse(File.read(".order"))
+                else
+                  {}
+                end
+
+    dst = Source.new(file, options)
+
+    src_methods = reference.map { |k, v| v }.flatten
+    dst_methods = dst.methods
+
+    src_set = Set.new(src_methods)
+    dst_set = Set.new(dst_methods)
+
+    intersection = src_set & dst_set
+    intersection.delete("initialize")
+
+    loop do
+      src_methods = reference.map { |k, v| v }.flatten
+      dst_methods = dst.methods
+
+      src_methods = src_methods.select do |m|
+        intersection.include?(m)
+      end
+
+      dst_methods = dst_methods.select do |m|
+        intersection.include?(m)
+      end
+
+      if src_methods == dst_methods
+        break
+      end
+
+      rv = yield(src_methods, dst_methods, dst)
+      break if rv == false
+    end
+
+    File.open(file, "w") do |f|
+      f.write(dst.to_s)
+    end
+  end
+
+  task :reorder do
+    blk = lambda do |src_methods, dst_methods, dst|
+      src_methods.zip(dst_methods).each do |a, b|
+        if a != b
+          dst.move(a, b)
+          break
+        end
+      end
+    end
+
+    reorder "lib/redis.rb", :indent => 2, &blk
+    reorder "lib/redis/distributed.rb", :indent => 4, &blk
+  end
+
+  def missing(file, options = {})
+    src = Source.new(file, options)
+
+    defined_methods = src.methods.map(&:downcase)
+    required_methods = redis_commands.map(&:downcase)
+
+    STDOUT.puts "missing in #{file}:"
+    STDOUT.puts (required_methods - defined_methods).inspect
+  end
+
+  task :missing do
+    missing "lib/redis.rb", :indent => 2
+    missing "lib/redis/distributed.rb", :indent => 4
+  end
+
+  def document(file)
+    source = File.read(file)
+
+    doc.each do |name, command|
+      source.sub!(/(?:^ *# .*\n)*(^ *#\n(^ *# .+?\n)*)*^( *)def #{name.downcase}(\(|$)/) do
+        extra_comments, indent, extra_args = $1, $3, $4
+        comment = "#{indent}# #{command["summary"].strip}."
+
+        IO.popen("par p#{2 + indent.size} 80", "r+") do |io|
+          io.puts comment
+          io.close_write
+          comment = io.read
+        end
+
+        "#{comment}#{extra_comments}#{indent}def #{name.downcase}#{extra_args}"
+      end
+    end
+
+    File.open(file, "w") { |f| f.write(source) }
+  end
+
+  task :doc do
+    document "lib/redis.rb"
+    document "lib/redis/distributed.rb"
+  end
+
+  task :verify do
+    require "redis"
+    require "stringio"
+
+    require "./test/helper"
+
+    OPTIONS[:logger] = Logger.new("./tmp/log")
+
+    Rake::Task["test:ruby"].invoke
+
+    redis = Redis2.new
+
+    report = ["Command", "\033[0mDefined?\033[0m", "\033[0mTested?\033[0m"]
+
+    yes, no = "\033[1;32mYes\033[0m", "\033[1;31mNo\033[0m"
+
+    log = File.read("./tmp/log")
+
+    redis_commands.sort.each do |name, _|
+      defined, tested = redis.respond_to?(name), log[">> #{name.upcase}"]
+
+      next if defined && tested
+
+      report << name
+      report << (defined ? yes : no)
+      report << (tested ? yes : no)
+    end
+
+    IO.popen("rs 0 3", "w") do |io|
+      io.puts report.join("\n")
+    end
+  end
+end

data/benchmarking/logging.rb

@@ -0,0 +1,71 @@
+# Run with
+#
+#   $ ruby -Ilib benchmarking/logging.rb
+#
+
+begin
+  require "bench"
+rescue LoadError
+  $stderr.puts "`gem install bench` and try again."
+  exit 1
+end
+
+require "redis"
+require "logger"
+
+def log(level, namespace = nil)
+  logger = (namespace || Kernel).const_get(:Logger).new("/dev/null")
+  logger.level = (namespace || Logger).const_get(level)
+  logger
+end
+
+def stress(redis)
+  redis.flushdb
+
+  n = (ARGV.shift || 2000).to_i
+
+  n.times do |i|
+    key = "foo:#{i}"
+    redis.set key, i
+    redis.get key
+  end
+end
+
+default = Redis2.new
+
+logging_redises = [
+  Redis2.new(:logger => log(:DEBUG)),
+  Redis2.new(:logger => log(:INFO)),
+]
+
+begin
+  require "log4r"
+
+  logging_redises += [
+    Redis2.new(:logger => log(:DEBUG, Log4r)),
+    Redis2.new(:logger => log(:INFO, Log4r)),
+  ]
+rescue LoadError
+  $stderr.puts "Log4r not installed. `gem install log4r` if you want to compare it against Ruby's Logger (spoiler: it's much faster)."
+end
+
+benchmark "Default options (no logger)" do
+  stress(default)
+end
+
+logging_redises.each do |redis|
+  logger = redis.client.logger
+
+  case logger
+  when Logger
+    level = Logger::SEV_LABEL[logger.level]
+  when Log4r::Logger
+    level = logger.levels[logger.level]
+  end
+
+  benchmark "#{logger.class} on #{level}" do
+    stress(redis)
+  end
+end
+
+run 10