redis-expiring-set 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in redis-expiring-set.gemspec
+gemspec

data/README.markdown

@@ -0,0 +1,92 @@
+# Redis::ExpiringSet
+
+## Purpose
+
+Redis::ExpiringSet provides a very specific but useful data-type to your Redis
+environment - a set of objects where each has its own specified expiration time.
+
+Imagine, for example, that you want to keep details on every email that your
+system sent out in the last 24 hours. Dump the data into an ExpiringSet with a
+24-hour expiration time and let the set manage itself - you'll only ever see
+data that is no more than 24 hours old.
+
+## Usage
+
+The commands for Redis::ExpiringSet are designed to closely mirror those Redis
+already has in place for working with sets. As of this release the commands are
+not a complete copy of what's available for working with sets in Redis, but they
+serve to be functional. Example usage:
+
+    require 'redis-expiring-set'
+
+    redis = Redis.new
+    expset = Redis::ExpiringSet.new(redis)
+
+    # add "something" to the set "some_set" that expires in 10 seconds
+    expset.xadd "some_set", "something", Time.now + 10
+    # This does the same thing; pass in a number instead of a Time object and it
+    # assumes you mean "expire x seconds from now"
+    expset.xadd "some_set", "something", 10
+
+    # Decide you want to remove the item before it expires? OK:
+    expset.xrem "some_set", "something"
+
+    # Need to know how big the set is?
+    expset.xcard "some_set"
+
+    # Want to actually look at your data?
+    expset.xmembers "some_set"
+
+    # By default, expired items are removed any time you go to read values
+    # (currently, when you call xcard and xmembers). If you want to clear them
+    # manually, though, you can use:
+    expset.xclearexpired "some_set"
+
+## Alternate Usage
+
+"Ugh, you mean I have to instantiate some new object and use that to interact
+with this new data type?"
+
+Not if you don't want to. There's an optional file you can require which
+monkeypatches these methods onto the Redis class so that you can use it without
+ever having to touch an instance of Redis::ExpiringSet. Example:
+
+    require 'redis-expiring-set/monkeypatch'
+
+At this point you can use `xadd`, `xrem`, `xcard`, `xmembers`, and
+`xclearexpired` just like they were native redis methods. This just isn't the
+default functionality because I don't want you to have to monkeypatch Redis for
+this if you don't want to.
+
+## Performance
+
+Redis::ExpiredSet uses nothing but native Redis functions to manipulate data,
+and under the hood we use sorted sets. Expiring items in the cache is only done
+when it's absolutely necessary, so there should be a minimal number of
+unnecessary operations.
+
+BUT, obviously, one of the chief advantages of using Redis is the performance,
+so if you notice anything that might make this library any more performant, I'd
+be glad to hear about it.
+
+## Contributions
+
+If Redis::ExpiringSet interests you and you think you might want to contribute, hit me up
+over Github. You can also just fork it and make some changes, but there's a
+better chance that your work won't be duplicated or rendered obsolete if you
+check in on the current development status first.
+
+## Development notes
+
+You need Redis installed to do development on Redis::ExpiringSet, and currently the test
+suites assume that you're using the default configurations for Redis. That
+should probably change, but it probably won't until someone needs it to.
+
+Gem requirements/etc. should be handled by Bundler.
+
+## License
+Copyright (C) 2012 by Tommy Morgan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/unit/test_*.rb']
+  t.verbose = true
+  t.warning = true
+end

data/lib/redis-expiring-set.rb

@@ -0,0 +1,46 @@
+require "forwardable"
+
+require "redis"
+require "redis-expiring-set/version"
+
+
+class Redis
+  module ExpiringSetMethods
+    def xadd(key, value, expires)
+      if expires.is_a? Numeric
+        expires = Time.now + expires
+      end
+
+      zadd(key, expires.to_f, value)
+    end
+
+    def xrem(key, value)
+      zrem(key, value)
+    end
+
+    def xmembers(key)
+      xclearexpired(key)
+      zrangebyscore(key, -Float::INFINITY, Float::INFINITY)
+    end
+
+    def xclearexpired(key)
+      zremrangebyscore key, -Float::INFINITY, Time.now.to_f.to_i
+    end
+
+    def xcard(key)
+      xclearexpired(key)
+      zcard(key)
+    end
+  end
+
+  class ExpiringSet
+    extend Forwardable
+    include ExpiringSetMethods
+
+    def_delegators :@redis, :zadd, :zcard, :zrem, :zrangebyscore, :zremrangebyscore
+
+    def initialize(redis)
+      @redis = redis
+    end
+  end
+end

data/lib/redis-expiring-set/monkeypatch.rb

@@ -0,0 +1,3 @@
+class Redis
+  include Redis::ExpiringSetMethods
+end

data/lib/redis-expiring-set/version.rb

@@ -0,0 +1,5 @@
+class Redis
+  class ExpiringSet
+    VERSION = "0.1.0"
+  end
+end

data/redis-expiring-set.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "redis-expiring-set/version"
+
+Gem::Specification.new do |s|
+  s.name        = "redis-expiring-set"
+  s.version     = Redis::ExpiringSet::VERSION
+  s.authors     = ["Tommy Morgan"]
+  s.email       = ["tommy.morgan@gmail.com"]
+  s.homepage    = "http://github.com/duwanis/redis-expiring-set"
+  s.summary     = %q{Add an expiring set to redis.}
+  s.description = %q{Add some commands to Redis that make it easy to work with a set of objects that need to expire individually.}
+
+  s.rubyforge_project = "redis-expiring-set"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+  s.add_runtime_dependency "redis"
+end

data/test/partial_minispec.rb

@@ -0,0 +1,229 @@
+## This is code stolen from the definition file for Minitest::Spec. We really
+# like everything about Minitest::Spec except for the expectations part, so we
+# are stealing it and using it here. Shamelessly. 
+#
+# This code may go out of date in future versions of Ruby, so we should keep an
+# eye on that. But that's better than reinventing the wheel.
+
+module Kernel # :nodoc:
+  ##
+  # Describe a series of expectations for a given target +desc+.
+  #
+  # TODO: find good tutorial url.
+  #
+  # Defines a test class subclassing from either MiniTest::Spec or
+  # from the surrounding describe's class. The surrounding class may
+  # subclass MiniTest::Spec manually in order to easily share code:
+  #
+  #     class MySpec < MiniTest::Spec
+  #       # ... shared code ...
+  #     end
+  #
+  #     class TestStuff < MySpec
+  #       it "does stuff" do
+  #         # shared code available here
+  #       end
+  #       describe "inner stuff" do
+  #         it "still does stuff" do
+  #           # ...and here
+  #         end
+  #       end
+  #     end
+
+  def describe desc, additional_desc = nil, &block # :doc:
+    stack = MiniTest::Spec.describe_stack
+    name  = [stack.last, desc, additional_desc].compact.join("::")
+    sclas = stack.last || if Class === self && self < MiniTest::Spec then
+                            self
+                          else
+                            MiniTest::Spec.spec_type desc
+                          end
+
+    cls = sclas.create name, desc
+
+    stack.push cls
+    cls.class_eval(&block)
+    stack.pop
+    cls
+  end
+  private :describe
+end
+
+##
+# MiniTest::Spec -- The faster, better, less-magical spec framework!
+#
+# For a list of expectations, see MiniTest::Expectations.
+
+class MiniTest::Spec < MiniTest::Unit::TestCase
+  ##
+  # Contains pairs of matchers and Spec classes to be used to
+  # calculate the superclass of a top-level describe. This allows for
+  # automatically customizable spec types.
+  #
+  # See: register_spec_type and spec_type
+
+  TYPES = [[//, MiniTest::Spec]]
+
+  ##
+  # Register a new type of spec that matches the spec's description.
+  # This method can take either a Regexp and a spec class or a spec
+  # class and a block that takes the description and returns true if
+  # it matches.
+  #
+  # Eg:
+  #
+  #     register_spec_type(/Controller$/, MiniTest::Spec::Rails)
+  #
+  # or:
+  #
+  #     register_spec_type(MiniTest::Spec::RailsModel) do |desc|
+  #       desc.superclass == ActiveRecord::Base
+  #     end
+
+  def self.register_spec_type(*args, &block)
+    if block then
+      matcher, klass = block, args.first
+    else
+      matcher, klass = *args
+    end
+    TYPES.unshift [matcher, klass]
+  end
+
+  ##
+  # Figure out the spec class to use based on a spec's description. Eg:
+  #
+  #     spec_type("BlahController") # => MiniTest::Spec::Rails
+
+  def self.spec_type desc
+    TYPES.find { |matcher, klass|
+      if matcher.respond_to? :call then
+        matcher.call desc
+      else
+        matcher === desc.to_s
+      end
+    }.last
+  end
+
+  @@describe_stack = []
+  def self.describe_stack # :nodoc:
+    @@describe_stack
+  end
+
+  ##
+  # Returns the children of this spec.
+
+  def self.children
+    @children ||= []
+  end
+
+  def self.nuke_test_methods! # :nodoc:
+    self.public_instance_methods.grep(/^test_/).each do |name|
+      self.send :undef_method, name
+    end
+  end
+
+  ##
+  # Define a 'before' action. Inherits the way normal methods should.
+  #
+  # NOTE: +type+ is ignored and is only there to make porting easier.
+  #
+  # Equivalent to MiniTest::Unit::TestCase#setup.
+
+  def self.before type = :each, &block
+    raise "unsupported before type: #{type}" unless type == :each
+
+    add_setup_hook {|tc| tc.instance_eval(&block) }
+  end
+
+  ##
+  # Define an 'after' action. Inherits the way normal methods should.
+  #
+  # NOTE: +type+ is ignored and is only there to make porting easier.
+  #
+  # Equivalent to MiniTest::Unit::TestCase#teardown.
+
+  def self.after type = :each, &block
+    raise "unsupported after type: #{type}" unless type == :each
+
+    add_teardown_hook {|tc| tc.instance_eval(&block) }
+  end
+
+  ##
+  # Define an expectation with name +desc+. Name gets morphed to a
+  # proper test method name. For some freakish reason, people who
+  # write specs don't like class inheritence, so this goes way out of
+  # its way to make sure that expectations aren't inherited.
+  #
+  # This is also aliased to #specify and doesn't require a +desc+ arg.
+  #
+  # Hint: If you _do_ want inheritence, use minitest/unit. You can mix
+  # and match between assertions and expectations as much as you want.
+
+  def self.it desc = "anonymous", &block
+    block ||= proc { skip "(no tests defined)" }
+
+    @specs ||= 0
+    @specs += 1
+
+    name = "test_%04d_%s" % [ @specs, desc.gsub(/\W+/, '_').downcase ]
+
+    define_method name, &block
+
+    self.children.each do |mod|
+      mod.send :undef_method, name if mod.public_method_defined? name
+    end
+  end
+
+  ##
+  # Essentially, define an accessor for +name+ with +block+.
+  #
+  # Why use let instead of def? I honestly don't know.
+
+  def self.let name, &block
+    define_method name do
+      @_memoized ||= {}
+      @_memoized.fetch(name) { |k| @_memoized[k] = instance_eval(&block) }
+    end
+  end
+
+  ##
+  # Another lazy man's accessor generator. Made even more lazy by
+  # setting the name for you to +subject+.
+
+  def self.subject &block
+    let :subject, &block
+  end
+
+  def self.create name, desc # :nodoc:
+    cls = Class.new(self) do
+      @name = name
+      @desc = desc
+
+      nuke_test_methods!
+    end
+
+    children << cls
+
+    cls
+  end
+
+  def self.to_s # :nodoc:
+    defined?(@name) ? @name : super
+  end
+
+  # :stopdoc:
+  def after_setup
+    run_setup_hooks
+  end
+
+  def before_teardown
+    run_teardown_hooks
+  end
+
+  class << self
+    attr_reader :desc
+    alias :specify :it
+    alias :name :to_s
+  end
+  # :startdoc:
+end

data/test/test_helper.rb

@@ -0,0 +1,12 @@
+require 'test/unit'
+
+require 'partial_minispec'
+
+# include the gem
+require 'redis-expiring-set'
+
+# Use database 15 for testing, so we don't risk overwriting any data that's
+# actually useful
+def clear_test_db
+  Redis.new(:db => 15).flushdb
+end

data/test/unit/test_monkeypatched.rb

@@ -0,0 +1,43 @@
+require 'test_helper'
+require 'redis-expiring-set/monkeypatch'
+
+describe Redis::ExpiringSet do
+  describe "newly instantiated" do
+    before do
+      @redis = Redis.new(:db => 15)
+    end
+
+    after do
+      clear_test_db
+    end
+
+    it "allows things to be added to expiration sets using xadd" do
+      assert_equal true, @redis.xadd("some_set", "some_value", Time.now + 10)
+    end
+
+    it "allows expiration to set in terms of seconds as well" do
+      assert_equal true, @redis.xadd("some_set", "some_value", 60)
+    end
+
+    it "allows items to be removed from expiration sets using xrem" do
+      assert_equal true, @redis.xadd("some_set", "some_value", 60)
+      assert_equal true, @redis.xrem("some_set", "some_value")
+    end
+
+    it "allows for all items in an expiration set to be returned by xmembers" do
+      assert_equal true, @redis.xadd("some_set", "some_value", 300)
+      assert_equal ["some_value"], @redis.xmembers("some_set")
+    end
+
+    it "doesn't include any already expired items in xmembers" do
+      assert_equal true, @redis.xadd("some_set", "some_value", Time.now - 100)
+      assert_equal [], @redis.xmembers("some_set")
+    end
+
+    it "allows for a count of items in an expiration set using xcard" do
+      assert_equal 0, @redis.xcard("some_set")
+      assert_equal true, @redis.xadd("some_set", "some_value", 60)
+      assert_equal 1, @redis.xcard("some_set")
+    end
+  end
+end

data/test/unit/test_namespaced.rb

@@ -0,0 +1,43 @@
+require 'test_helper'
+
+describe Redis::ExpiringSet do
+  describe "newly instantiated" do
+    before do
+      @redis = Redis.new(:db => 15)
+      @expset = Redis::ExpiringSet.new(@redis)
+    end
+
+    after do
+      clear_test_db
+    end
+
+    it "allows things to be added to expiration sets using xadd" do
+      assert_equal true, @expset.xadd("some_set", "some_value", Time.now + 10)
+    end
+
+    it "allows expiration to set in terms of seconds as well" do
+      assert_equal true, @expset.xadd("some_set", "some_value", 60)
+    end
+
+    it "allows items to be removed from expiration sets using xrem" do
+      assert_equal true, @expset.xadd("some_set", "some_value", 60)
+      assert_equal true, @expset.xrem("some_set", "some_value")
+    end
+
+    it "allows for all items in an expiration set to be returned by xmembers" do
+      assert_equal true, @expset.xadd("some_set", "some_value", 300)
+      assert_equal ["some_value"], @expset.xmembers("some_set")
+    end
+
+    it "doesn't include any already expired items in xmembers" do
+      assert_equal true, @expset.xadd("some_set", "some_value", Time.now - 100)
+      assert_equal [], @expset.xmembers("some_set")
+    end
+
+    it "allows for a count of items in an expiration set using xcard" do
+      assert_equal 0, @expset.xcard("some_set")
+      assert_equal true, @expset.xadd("some_set", "some_value", 60)
+      assert_equal 1, @expset.xcard("some_set")
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: redis-expiring-set
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Tommy Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: &70159947898960 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70159947898960
+description: Add some commands to Redis that make it easy to work with a set of objects
+  that need to expire individually.
+email:
+- tommy.morgan@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.markdown
+- Rakefile
+- lib/redis-expiring-set.rb
+- lib/redis-expiring-set/monkeypatch.rb
+- lib/redis-expiring-set/version.rb
+- redis-expiring-set.gemspec
+- test/partial_minispec.rb
+- test/test_helper.rb
+- test/unit/test_monkeypatched.rb
+- test/unit/test_namespaced.rb
+homepage: http://github.com/duwanis/redis-expiring-set
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: redis-expiring-set
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Add an expiring set to redis.
+test_files:
+- test/partial_minispec.rb
+- test/test_helper.rb
+- test/unit/test_monkeypatched.rb
+- test/unit/test_namespaced.rb