redis-objects 0.1.0

data/lib/redis/list.rb

@@ -0,0 +1,95 @@
+class Redis
+  #
+  # Class representing a Redis list.  Instances of Redis::List are designed to 
+  # behave as much like Ruby arrays as possible.
+  #
+  class List
+    attr_reader :key, :options, :redis
+    def initialize(key, options={})
+      @key = key
+      @options = options
+      @redis   = options[:redis] || $redis || Redis::Objects.redis
+      @options[:start] ||= 0
+      @options[:type]  ||= @options[:start] == 0 ? :increment : :decrement
+      @redis.setnx(key, @options[:start]) unless @options[:start] == 0 || @options[:init] === false
+    end
+
+    def <<(value)
+      push(value)
+    end
+    
+    def push(value)
+      redis.rpush(key, value)
+      @values << value
+    end
+
+    def pop
+      redis.rpop(key)
+      @values.pop
+    end
+
+    def unshift(value)
+      redis.lpush(key, value)
+      @values.unshift value
+    end
+
+    def shift
+      redis.lpop(key)
+    end
+
+    def values
+      @values ||= get
+    end
+
+    def value=(val)
+      redis.set(key, val)
+      @values = val
+    end
+    
+    def get
+      @values = range(0, -1)
+    end
+    
+    def [](index)
+      case index
+      when Range
+        range(index.first, index.last)
+      else
+        range(index, index)
+      end
+    end
+    
+    def delete(name, count=0)
+      redis.lrem(name, count)
+    end
+
+    def range(start_index, end_index)
+      redis.lrange(key, start_index, end_index)
+    end
+ 
+    def at(index)
+      redis.lrange(key, index, index)
+    end
+
+    def last
+      redis.lrange(key, -1, -1)
+    end
+
+    def clear
+      redis.del(key)
+    end
+
+    def length
+      redis.length
+    end
+    alias_method :size, :length
+    
+    def empty?
+      values.empty?
+    end
+    
+    def ==(x)
+      values == x
+    end
+  end
+end

data/lib/redis/lock.rb

@@ -0,0 +1,47 @@
+class Redis
+  #
+  # Class representing a lock.  This functions like a proxy class, in
+  # that you can say @object.lock_name { block } to use the lock and also
+  # @object.counter_name.clear to reset on it.  You can use this
+  # directly, but it is better to use the lock :foo class method in your
+  # class to define a lock.
+  #
+  class Lock
+    class LockTimeout < StandardError; end #:nodoc:
+
+    attr_reader :key, :options, :redis
+    def initialize(key, options={})
+      @key = key
+      @options = options
+      @options[:timeout] ||= 5
+      @redis = options[:redis] || $redis || Redis::Objects.redis
+      @redis.setnx(key, @options[:start]) unless @options[:start] == 0 || @options[:init] === false
+    end
+
+    # Clear the lock.  Should only be needed if there's a server crash
+    # or some other event that gets locks in a stuck state.
+    def clear
+      redis.del(key)
+    end
+    alias_method :delete, :clear
+
+    # Get the lock and execute the code block. Any other code that needs the lock
+    # (on any server) will spin waiting for the lock up to the :timeout
+    # that was specified when the lock was defined.
+    def lock(&block)
+      start = Time.now
+      gotit = false
+      while Time.now - start < @options[:timeout]
+        gotit = redis.setnx(key, 1)
+        break if gotit
+        sleep 0.1
+      end
+      raise LockTimeout, "Timeout on lock #{key} exceeded #{@options[:timeout]} sec" unless gotit
+      begin
+        yield
+      ensure
+        redis.del(key)
+      end
+    end
+  end
+end

data/lib/redis/objects.rb

@@ -0,0 +1,103 @@
+# Redis::Objects - Lightweight object layer around redis-rb
+# See README.rdoc for usage and approach.
+require 'redis'
+class Redis
+  #
+  # Redis::Objects enables high-performance atomic operations in your app
+  # by leveraging the atomic features of the Redis server.  To use Redis::Objects,
+  # first include it in any class you want.  (This example uses an ActiveRecord
+  # subclass, but that is *not* required.) Then, use +counter+ and +lock+
+  # to define your primitives:
+  #
+  #   class Game < ActiveRecord::Base
+  #     include Redis::Objects
+  #
+  #     counter :joined_players
+  #     counter :active_players
+  #     set :player_ids
+  #     lock :archive_game
+  #   end
+  # 
+  # The, you can use these counters both for bookeeping and as atomic actions:
+  #
+  #   @game = Game.find(id)
+  #   @game_user = @game.joined_players.increment do |val|
+  #     break if val > @game.max_players
+  #     gu = @game.game_users.create!(:user_id => @user.id)
+  #     @game.active_players.increment
+  #     gu
+  #   end
+  #   if @game_user.nil?
+  #     # game is full - error screen
+  #   else
+  #     # success
+  #   end
+  #
+  #
+  #
+  module Objects
+    dir = File.expand_path(__FILE__.sub(/\.rb$/,''))
+
+    autoload :Counters, File.join(dir, 'counters')
+    autoload :Values, File.join(dir, 'values')
+    autoload :Lists, File.join(dir, 'lists')
+    autoload :Sets, File.join(dir, 'sets')
+    autoload :Locks, File.join(dir, 'locks')
+
+    class NotConnected  < StandardError; end
+
+    class << self
+      def redis=(conn) @redis = conn end
+      def redis
+        @redis ||= $redis || raise(NotConnected, "Redis::Objects.redis not set to a Redis.new connection")
+      end
+
+      def included(klass)
+        # Core (this file)
+        klass.instance_variable_set('@redis', @redis)
+        klass.send :include, InstanceMethods
+        klass.extend ClassMethods
+        
+        # Adapted from Redis::Model for marshaling complex data
+        require 'redis/data_types'
+        klass.send :include, Redis::DataTypes
+        
+        # Pull in each object type
+        klass.send :include, Redis::Objects::Counters
+        klass.send :include, Redis::Objects::Values
+        klass.send :include, Redis::Objects::Lists
+        klass.send :include, Redis::Objects::Sets
+        klass.send :include, Redis::Objects::Locks
+      end
+    end
+
+    # Class methods that appear in your class when you include Redis::Objects.
+    module ClassMethods
+      attr_accessor :redis
+      
+
+      # Set the Redis prefix to use. Defaults to model_name
+      def prefix=(prefix) @prefix = prefix end
+      def prefix #:nodoc:
+        @prefix ||= self.name.to_s.
+          sub(%r{(.*::)}, '').
+          gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+          gsub(/([a-z\d])([A-Z])/,'\1_\2').
+          downcase
+      end
+      
+      def field_key(name, id) #:nodoc:
+        "#{prefix}:#{id}:#{name}"
+      end
+
+    end
+
+    # Instance methods that appear in your class when you include Redis::Objects.
+    module InstanceMethods
+      def redis() self.class.redis end
+      def field_key(name) #:nodoc:
+        self.class.field_key(name, id)
+      end
+    end
+  end
+end

data/lib/redis/objects/counters.rb

@@ -0,0 +1,113 @@
+# This is the class loader, for use as "include Redis::Objects::Counters"
+# For the object itself, see "Redis::Counter"
+require 'redis/counter'
+class Redis
+  module Objects
+    class UndefinedCounter < StandardError; end #:nodoc:
+    module Counters
+      def self.included(klass)
+        klass.instance_variable_set('@counters', {})
+        klass.instance_variable_set('@initialized_counters', {})
+        klass.send :include, InstanceMethods
+        klass.extend ClassMethods
+      end
+
+      # Class methods that appear in your class when you include Redis::Objects.
+      module ClassMethods
+        attr_reader :counters, :initialized_counters
+
+        # Define a new counter.  It will function like a regular instance
+        # method, so it can be used alongside ActiveRecord, DataMapper, etc.
+        def counter(name, options={})
+          options[:start] ||= 0
+          options[:type]  ||= options[:start] == 0 ? :increment : :decrement
+          @counters[name] = options
+          class_eval <<-EndMethods
+            def #{name}
+              @#{name} ||= Redis::Counter.new(field_key(:#{name}), self.class.counters[:#{name}].merge(:redis => redis))
+            end
+          EndMethods
+        end
+
+        # Get the current value of the counter. It is more efficient
+        # to use the instance method if possible.
+        def get_counter(name, id)
+          verify_counter_defined!(name)
+          initialize_counter!(name, id)
+          redis.get(field_key(name, id)).to_i
+        end
+
+        # Increment a counter with the specified name and id.  Accepts a block
+        # like the instance method.  See Redis::Objects::Counter for details.
+        def increment_counter(name, id, by=1, &block)
+          verify_counter_defined!(name)
+          initialize_counter!(name, id)
+          value = redis.incr(field_key(name, id), by).to_i
+          block_given? ? rewindable_block(:decrement_counter, name, id, value, &block) : value
+        end
+
+        # Decrement a counter with the specified name and id.  Accepts a block
+        # like the instance method.  See Redis::Objects::Counter for details.
+        def decrement_counter(name, id, by=1, &block)
+          verify_counter_defined!(name)
+          initialize_counter!(name, id)
+          value = redis.decr(field_key(name, id), by).to_i
+          block_given? ? rewindable_block(:increment_counter, name, id, value, &block) : value
+        end
+
+        # Reset a counter to its starting value.
+        def reset_counter(name, id, to=nil)
+          verify_counter_defined!(name)
+          to = @counters[name][:start] if to.nil?
+          redis.set(field_key(name, id), to)
+        end
+        
+        private
+        
+        def verify_counter_defined!(name) #:nodoc:
+          raise Redis::Objects::UndefinedCounter, "Undefined counter :#{name} for class #{self.name}" unless @counters.has_key?(name)
+        end
+        
+        def initialize_counter!(name, id) #:nodoc:
+          key = field_key(name, id)
+          unless @initialized_counters[key]
+            redis.setnx(key, @counters[name][:start])
+          end
+          @initialized_counters[key] = true
+        end
+        
+        # Implements increment/decrement blocks on a class level
+        def rewindable_block(rewind, name, id, value, &block) #:nodoc:
+          # Unfortunately this is almost exactly duplicated from Redis::Counter
+          raise ArgumentError, "Missing block to rewindable_block somehow" unless block_given?
+          ret = nil
+          begin
+            ret = yield value
+          rescue
+            send(rewind, name, id)
+            raise
+          end
+          send(rewind, name, id) if ret.nil?
+          ret
+        end
+      end
+
+      # Instance methods that appear in your class when you include Redis::Objects.
+      module InstanceMethods
+        # Increment a counter.
+        # It is more efficient to use increment_[counter_name] directly.
+        # This is mainly just for completeness to override ActiveRecord.
+        def increment(name, by=1)
+          send(name).increment(by)
+        end
+
+        # Decrement a counter.
+        # It is more efficient to use increment_[counter_name] directly.
+        # This is mainly just for completeness to override ActiveRecord.
+        def decrement(name, by=1)
+          send(name).decrement(by)
+        end
+      end
+    end
+  end
+end

data/lib/redis/objects/lists.rb

@@ -0,0 +1,34 @@
+# This is the class loader, for use as "include Redis::Objects::Lists"
+# For the object itself, see "Redis::List"
+require 'redis/list'
+class Redis
+  module Objects
+    module Lists
+      def self.included(klass)
+        klass.instance_variable_set('@lists', {})
+        klass.send :include, InstanceMethods
+        klass.extend ClassMethods
+      end
+
+      # Class methods that appear in your class when you include Redis::Objects.
+      module ClassMethods
+        attr_reader :lists
+
+        # Define a new list.  It will function like a regular instance
+        # method, so it can be used alongside ActiveRecord, DataMapper, etc.
+        def list(name, options={})
+          @lists[name] = options
+          class_eval <<-EndMethods
+            def #{name}
+              @#{name} ||= Redis::List.new(field_key(:#{name}), self.class.lists[:#{name}].merge(:redis => redis))
+            end
+          EndMethods
+        end
+      end
+
+      # Instance methods that appear in your class when you include Redis::Objects.
+      module InstanceMethods
+      end
+    end
+  end
+end

data/lib/redis/objects/locks.rb

@@ -0,0 +1,56 @@
+# This is the class loader, for use as "include Redis::Objects::Locks"
+# For the object itself, see "Redis::Lock"
+require 'redis/lock'
+class Redis
+  module Objects
+    class UndefinedLock < StandardError; end #:nodoc:
+    module Locks
+      def self.included(klass)
+        klass.instance_variable_set('@locks', {})
+        klass.send :include, InstanceMethods
+        klass.extend ClassMethods
+      end
+
+      # Class methods that appear in your class when you include Redis::Objects.
+      module ClassMethods
+        attr_reader :locks
+
+        # Define a new lock.  It will function like a model attribute,
+        # so it can be used alongside ActiveRecord/DataMapper, etc.
+        def lock(name, options={})
+          options[:timeout] ||= 5  # seconds
+          @locks[name] = options
+          class_eval <<-EndMethods
+            def #{name}_lock(&block)
+              @#{name}_lock ||= Redis::Lock.new(field_key(:#{name}_lock), self.class.locks[:#{name}].merge(:redis => redis))
+            end
+          EndMethods
+        end
+
+        # Obtain a lock, and execute the block synchronously.  Any other code
+        # (on any server) will spin waiting for the lock up to the :timeout
+        # that was specified when the lock was defined.
+        def obtain_lock(name, id, &block)
+          verify_lock_defined!(name)
+          raise ArgumentError, "Missing block to #{self.name}.obtain_lock" unless block_given?
+          lock_name = field_key("#{name}_lock", id)
+          Redis::Lock.new(redis, lock_name, self.class.locks[name]).lock(&block)
+        end
+
+        # Clear the lock.  Use with care - usually only in an Admin page to clear
+        # stale locks (a stale lock should only happen if a server crashes.)
+        def clear_lock(name, id)
+          verify_lock_defined!(name)
+          lock_name = field_key("#{name}_lock", id)
+          redis.del(lock_name)
+        end
+        
+        private
+        
+        def verify_lock_defined!(name)
+          raise Redis::Objects::UndefinedLock, "Undefined lock :#{name} for class #{self.name}" unless @locks.has_key?(name)
+        end
+      end
+    end
+  end
+end