frivol 0.1.4 → 0.1.5

data/lib/frivol.rb

@@ -28,6 +28,21 @@
 # The <tt>expire_storage(time)</tt> method can be used to set the expiry time in seconds of the temporary storage. 
 # The default is not to expire the storage, in which case it will live for as long as Redis keeps it. 
 # <tt>delete_storage</tt>, as the name suggests will immediately delete the storage.
+#
+# Since version 0.1.5 Frivol can create different storage buckets. Note that this introduces a breaking change
+# to the <tt>storage_key</tt> method if you have overriden it. It now takes a +bucket+ parameter.
+#
+# Buckets can have their own expiry time and there are special counter buckets which simply keep an integer count.
+#
+#   storage_bucket :my_bucket, :expires_in => 5.minutes
+#   storage_bucket :my_counter, :counter => true
+#
+# Given the above, Frivol will create <tt>store_my_bucket</tt> and <tt>retrieve_my_bucket</tt> methods which work
+# exactly like the standard +store+ and +retrieve+ methods. There will also be <tt>store_my_counter</tt>,
+# <tt>retrieve_my_counter</tt> and <tt>increment_my_counter</tt> methods. The counter store and retrieve only
+# take a integer (value and default, respectively) and the increment does not take a parameter.
+# 
+# These methods are thread safe if you pass <tt>:thread_safe => true</tt> to the Redis configuration.
 # 
 # Frivol uses the +storage_key+ method to create a base key for storage in Redis. The current implementation uses
 # <tt>"#{self.class.name}-#{id}"</tt> so you'll want to override that method if you have classes that don't
@@ -44,8 +59,8 @@
 #       @key = key
 #     end
 #
-#     def storage_key
-#       "frivol-test-#{key}" # override the storage key because we don't respond_to? id
+#     def storage_key(bucket = nil)
+#       "frivol-test-#{key}" # override the storage key because we don't respond_to? :id, and don't care about buckets
 #     end
 #
 #     def big_complex_calc
@@ -69,6 +84,9 @@ require "redis"
 
 # == Frivol
 module Frivol
+  # Defines a constant to indicate that storage should never expire
+  NEVER_EXPIRE = nil
+  
   # Store a hash of keys and values.
   #
   # The hash need not be the complete hash of all things stored, just those you want to change.
@@ -77,11 +95,11 @@ module Frivol
   # is intended to be hidden and while it is true that it currently uses a <tt>Hash#to_json</tt> you should not
   # rely on this.
   def store(keys_and_values)
-    Frivol::Helpers.retrieve_hash self
+    hash = Frivol::Helpers.retrieve_hash(self)
     keys_and_values.each do |key, value|
-      @frivol_hash[key.to_s] = value
+      hash[key.to_s] = value
     end
-    Frivol::Helpers.store_hash self
+    Frivol::Helpers.store_hash(self, hash)
   end
   
   # Retrieve stored values, or defaults.
@@ -94,9 +112,9 @@ module Frivol
   # If the default is a symbol, Frivol will attempt to get the default from a method named after that symbol.
   # If the class does not <tt>respond_to?</tt> a method by that name, the symbol will assumed to be the default.
   def retrieve(keys_and_defaults)
-    Frivol::Helpers.retrieve_hash self
+    hash = Frivol::Helpers.retrieve_hash(self)
     result = keys_and_defaults.map do |key, default|
-      @frivol_hash[key.to_s] || (default.is_a?(Symbol) && respond_to?(default) && send(default)) || default
+      hash[key.to_s] || (default.is_a?(Symbol) && respond_to?(default) && send(default)) || default
     end
     return result.first if result.size == 1
     result
@@ -108,18 +126,22 @@ module Frivol
   end
   
   # Expire the stored data in +time+ seconds.
-  def expire_storage(time)
+  def expire_storage(time, bucket = nil)
     return if time.nil?
-    Frivol::Config.redis.expire storage_key, time
+    Frivol::Config.redis.expire storage_key(bucket), time
   end
   
   # The base key used for storage in Redis. 
   #
-  # This method has been implemented for use with ActiveRecord and uses <tt>"#{self.class.name}-#{id}"</tt>
+  # This method has been implemented for use with ActiveRecord and uses <tt>"#{self.class.name}-#{id}"</tt> 
+  # for the default bucket and <tt>"#{self.class.name}-#{id}-#{bucket}"</tt> for a named bucket.
   # If you are not using ActiveRecord, or using classes that don't respond to id, you should override
   # this method in your class.
-  def storage_key
+  #
+  # NOTE: This method has changed since version 0.1.4, and now has the bucket parameter (default: nil)
+  def storage_key(bucket = nil)
     @frivol_key ||= "#{self.class.name}-#{id}"
+    bucket.nil? ? @frivol_key : "#{@frivol_key}-#{bucket}"
   end
   
   # == Frivol::Config
@@ -156,46 +178,144 @@ module Frivol
   end
   
   module Helpers #:nodoc:
-    def self.store_hash(instance)
-      hash = instance.instance_variable_get(:@frivol_hash)
-      is_new = instance.instance_variable_get(:@frivol_is_new)
-      key = instance.send(:storage_key)
+    def self.store_hash(instance, hash, bucket = nil)
+      data, is_new = get_hash_and_is_new(instance, bucket)
+      data[bucket.to_s] = hash
+      
+      key = instance.send(:storage_key, bucket)
       Frivol::Config.redis[key] = hash.to_json
-      if is_new
-        instance.expire_storage instance.class.storage_expiry
-        instance.instance_variable_set :@frivol_is_new, false
+      
+      if is_new[bucket.to_s]
+        time = instance.class.storage_expiry(bucket)
+        Frivol::Config.redis.expire(key, time) if time != Frivol::NEVER_EXPIRE
+        is_new[bucket.to_s] = false
       end
     end
 
-    def self.retrieve_hash(instance)
-      return instance.instance_variable_get(:@frivol_hash) if instance.instance_variable_defined? :@frivol_hash
-      key = instance.send(:storage_key)
+    def self.retrieve_hash(instance, bucket = nil)
+      data, is_new = get_hash_and_is_new(instance, bucket)
+      return data[bucket.to_s] if data.key?(bucket.to_s)
+      key = instance.send(:storage_key, bucket)
       json = Frivol::Config.redis[key]
-      instance.instance_variable_set :@frivol_is_new, json.nil?
+      
+      is_new[bucket.to_s] = json.nil?
+      instance.instance_variable_set :@frivol_is_new, is_new
+      
       hash = json.nil? ? {} : JSON.parse(json)
-      instance.instance_variable_set :@frivol_hash, hash
+      data[bucket.to_s] = hash
+      instance.instance_variable_set :@frivol_data, data
+      
       hash
     end
     
-    def self.delete_hash(instance)
-      key = instance.send(:storage_key)
+    def self.delete_hash(instance, bucket = nil)
+      key = instance.send(:storage_key, bucket)
       Frivol::Config.redis.del key
-      instance.instance_variable_set :@frivol_hash, {}
+      
+      data = instance.instance_variable_defined?(:@frivol_data) ? instance.instance_variable_get(:@frivol_data) : {}
+      data.delete(bucket.to_s)
+      instance.instance_variable_set :@frivol_data, data
+    end
+    
+    def self.get_hash_and_is_new(instance, bucket)
+      data = instance.instance_variable_defined?(:@frivol_data) ? instance.instance_variable_get(:@frivol_data) : {}
+      is_new = instance.instance_variable_defined?(:@frivol_is_new) ? instance.instance_variable_get(:@frivol_is_new) : {}
+      [data, is_new]
+    end
+
+    def self.store_counter(instance, counter, value)
+      key = instance.send(:storage_key, counter)
+      Frivol::Config.redis[key] = value
+    end
+    
+    def self.retrieve_counter(instance, counter, default)
+      key = instance.send(:storage_key, counter)
+      (Frivol::Config.redis[key] || default).to_i
+    end
+
+    def self.increment_counter(instance, counter)
+      key = instance.send(:storage_key, counter)
+      Frivol::Config.redis.incr(key)
     end
   end
   
   # == Frivol::ClassMethods
   # These methods are available on the class level when Frivol is included in the class.
   module ClassMethods
-    # Set the storage expiry time in seconds.
-    def storage_expires_in(time)
-      @frivol_storage_expiry = time
+    # Set the storage expiry time in seconds for the default bucket or the bucket passed.
+    def storage_expires_in(time, bucket = nil)
+      @frivol_storage_expiry ||= {}
+      @frivol_storage_expiry[bucket.to_s] = time
     end
     
-    # Get the storage expiry time in seconds.
-    def storage_expiry
-      @frivol_storage_expiry
+    # Get the storage expiry time in seconds for the default bucket or the bucket passed.
+    def storage_expiry(bucket = nil)
+      @frivol_storage_expiry ||= {}
+      @frivol_storage_expiry.key?(bucket.to_s) ? @frivol_storage_expiry[bucket.to_s] : NEVER_EXPIRE
     end
+    
+    # Create a storage bucket.
+    # Frivol creates store_#{bucket} and retrieve_#{bucket} methods automatically.
+    # These methods work exactly like the default store and retrieve methods except that the bucket is 
+    # stored in it's own key in Redis and can have it's own expiry time.
+    #
+    # Counters are special in that they do not store a hash but only a single integer value and also
+    # that the data in a counter is not cached for the lifespan of the object, but rather each call
+    # hits Redis. This is intended to make counters thread safe (for example you may have multiple
+    # workers working on a job and they can each increment a progress counter which would not work
+    # with the default retrieve/store method that normal buckets use). For this to actually be thread safe
+    # you need to pass the thread safe option to the config when you make the connection.
+    #
+    # In the case of a counter, the methods work slightly differently:
+    # - store_#{bucket} only takes an integer value to store (no key)
+    # - retrieve_#{bucket} only takes an integer default, and returns only the integer value
+    # - there is an added increment_#{bucket} method which increments the counter by 1
+    #
+    # Options are :expires_in which sets the expiry time for a bucket,
+    # and :counter to create a special counter storage bucket.
+    def storage_bucket(bucket, options = {})
+      time = options[:expires_in]
+      storage_expires_in(time, bucket) if !time.nil?
+      is_counter = options[:counter]
+      
+      self.class_eval do
+        if is_counter
+          define_method "store_#{bucket}" do |value|
+            Frivol::Helpers.store_counter(self, bucket, value)
+          end
+      
+          define_method "retrieve_#{bucket}" do |default|
+            Frivol::Helpers.retrieve_counter(self, bucket, default)
+          end
+
+          define_method "increment_#{bucket}" do
+            Frivol::Helpers.increment_counter(self, bucket)
+          end
+        else
+          define_method "store_#{bucket}" do |keys_and_values|
+            hash = Frivol::Helpers.retrieve_hash(self, bucket)
+            keys_and_values.each do |key, value|
+              hash[key.to_s] = value
+            end
+            Frivol::Helpers.store_hash(self, hash, bucket)
+          end
+      
+          define_method "retrieve_#{bucket}" do |keys_and_defaults|
+            hash = Frivol::Helpers.retrieve_hash(self, bucket)
+            result = keys_and_defaults.map do |key, default|
+              hash[key.to_s] || (default.is_a?(Symbol) && respond_to?(default) && send(default)) || default
+            end
+            return result.first if result.size == 1
+            result
+          end
+        end
+      end
+    end
+    
+    # def storage_default(keys_and_defaults)
+    #   @frivol_defaults ||= {}
+    #   @frivol_defaults.merge keys_and_defaults
+    # end
   end
   
   def self.included(host) #:nodoc:

data/test/fake_redis.rb

@@ -21,11 +21,15 @@ class Redis
     @expires[key] = nil
   end
   
+  def incr(key)
+    @storage[key] += 1
+  end
+  
   def expire(key, time)
     @expires[key] = Time.now + time
   end
   
-  def flush_db
+  def flushdb
     @storage = {}
   end
 end

data/test/test_frivol.rb

@@ -2,12 +2,12 @@ require 'helper'
 
 class TestFrivol < Test::Unit::TestCase
   def setup 
-    #fake_redis # Comment out this line to test against a real live Redis
-    Frivol::Config.redis_config = {} # This will connect to a default Redis setup, otherwise set to { :host => "localhost", :port => 6379 }, for example
+    # fake_redis # Comment out this line to test against a real live Redis
+    Frivol::Config.redis_config = { :thread_safe => true } # This will connect to a default Redis setup, otherwise set to { :host => "localhost", :port => 6379 }, for example
   end
   
   def teardown
-    Frivol::Config.redis.flush_db
+    Frivol::Config.redis.flushdb
   end
   
   should "have a default storage key made up of the class name and id" do
@@ -86,7 +86,7 @@ class TestFrivol < Test::Unit::TestCase
 
   should "be able to override the key method" do
     class OverrideKeyTestClass < TestClass
-      def storage_key
+      def storage_key(bucket = nil)
         "my_storage"
       end
     end
@@ -130,10 +130,21 @@ class TestFrivol < Test::Unit::TestCase
     t.save
     t.expire_storage 0.5
     sleep 1
-    t = TestClass.new # Get a fresh instance so that the @frivol_hash is empty
+    t = TestClass.new # Get a fresh instance so that the @frivol_data is empty
     assert_equal "default", t.load
   end
   
+  should "use default expiry set on the class" do
+    class ExpiryTestClass < TestClass
+      storage_expires_in 0.5
+    end
+    t = ExpiryTestClass.new
+    t.save
+    sleep 1
+    t = TestClass.new # Get a fresh instance so that the @frivol_data is empty
+    assert_equal "default", t.load
+  end
+
   should "be able to include in other classes with storage expiry" do
     class BlankTestClass
     end
@@ -156,4 +167,125 @@ class TestFrivol < Test::Unit::TestCase
     t.delete_storage
     assert_equal "default", t.load
   end
+  
+  should "be able to create and use buckets" do
+    class SimpleBucketTestClass < TestClass
+      storage_bucket :blue
+    end
+    t = SimpleBucketTestClass.new
+    assert t.respond_to?(:store_blue)
+    assert t.respond_to?(:retrieve_blue)
+  end
+  
+  should "store different values in different buckets" do
+    class StorageBucketTestClass < TestClass
+      storage_bucket :blue
+      
+      def save_blue
+        store_blue :value => "blue value"
+      end
+      
+      def load_blue
+        retrieve_blue :value => "blue default"
+      end
+    end
+    t = StorageBucketTestClass.new
+    t.save
+    t.save_blue
+    assert_equal "value", t.load
+    assert_equal "blue value", t.load_blue
+  end
+
+  should "have different expiry times for different buckets" do
+    class ExpireBucketsTestClass < TestClass
+      storage_bucket :blue, :expires_in => 0.5
+      storage_expires_in 2
+    end
+    t = ExpireBucketsTestClass.new
+    assert_equal 0.5, ExpireBucketsTestClass.storage_expiry(:blue)
+    assert_equal 2, ExpireBucketsTestClass.storage_expiry
+  end
+
+  should "expire data in buckets" do
+    class ExpireBucketsTestClass < TestClass
+      storage_bucket :blue, :expires_in => 0.5
+      storage_expires_in 2
+      
+      def save_blue
+        store_blue :value => "blue value"
+      end
+      
+      def load_blue
+        retrieve_blue :value => "blue default"
+      end
+    end
+    t = ExpireBucketsTestClass.new
+    t.save
+    t.save_blue
+    sleep 1
+    t = ExpireBucketsTestClass.new # get a new instance so @frivol_data is empty
+    assert_equal "value", t.load
+    assert_equal "blue default", t.load_blue
+  end
+  
+  should "be able to create counter buckets" do
+    class SimpleCounterTestClass < TestClass
+      storage_bucket :blue, :counter => true
+    end
+    t = SimpleCounterTestClass.new
+    assert t.respond_to?(:store_blue)
+    assert t.respond_to?(:retrieve_blue)
+    assert t.respond_to?(:increment_blue)
+  end
+  
+  should "store, increment and retrieve integers in a counter" do
+    class IncrCounterTestClass < TestClass
+      storage_bucket :blue, :counter => true
+      
+      def save_blue
+        store_blue 10
+      end
+      
+      def load_blue
+        retrieve_blue 0
+      end
+    end
+    t = IncrCounterTestClass.new
+    assert_equal 0, t.load_blue
+    t.save_blue
+    assert_equal 10, t.load_blue
+    assert_equal 11, t.increment_blue
+    assert_equal 11, t.load_blue
+  end
+
+  should "have thread safe counters" do
+    class ThreadCounterTestClass < TestClass
+      storage_bucket :blue, :counter => true
+      
+      def save_blue
+        store_blue 10
+      end
+      
+      def load_blue
+        retrieve_blue 0
+      end
+    end
+    t = ThreadCounterTestClass.new
+    t.save_blue
+    assert_equal 10, t.load_blue
+    
+    threads = []
+    100.times do 
+      threads << Thread.new do
+        10.times do
+          temp = ThreadCounterTestClass.new
+          temp.increment_blue
+          sleep(rand(10) / 100.0)
+        end
+      end
+    end
+    threads.each { |a| a.join }
+      
+    assert_equal 1010, t.load_blue
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: frivol
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: false
   segments: 
   - 0
   - 1
-  - 4
-  version: 0.1.4
+  - 5
+  version: 0.1.5
 platform: ruby
 authors: 
 - Marc Heiligers
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-22 00:00:00 +02:00
+date: 2010-10-15 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -42,12 +42,12 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 31
+        hash: 27
         segments: 
-        - 0
-        - 1
         - 2
-        version: 0.1.2
+        - 0
+        - 10
+        version: 2.0.10
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
@@ -87,13 +87,18 @@ files:
 - doc/classes/Frivol.src/M000004.html
 - doc/classes/Frivol.src/M000005.html
 - doc/classes/Frivol.src/M000006.html
+- doc/classes/Frivol.src/M000007.html
 - doc/classes/Frivol/ClassMethods.html
 - doc/classes/Frivol/ClassMethods.src/M000007.html
 - doc/classes/Frivol/ClassMethods.src/M000008.html
+- doc/classes/Frivol/ClassMethods.src/M000009.html
+- doc/classes/Frivol/ClassMethods.src/M000010.html
 - doc/classes/Frivol/Config.html
 - doc/classes/Frivol/Config.src/M000009.html
 - doc/classes/Frivol/Config.src/M000010.html
 - doc/classes/Frivol/Config.src/M000011.html
+- doc/classes/Frivol/Config.src/M000012.html
+- doc/classes/Frivol/Config.src/M000013.html
 - doc/classes/Time.html
 - doc/classes/Time.src/M000001.html
 - doc/classes/Time.src/M000002.html