find_cache 0.1.6 → 0.1.7

data/README.rdoc

@@ -1,10 +1,10 @@
-# FindCache
+== FindCache
 
 It is simply an ActiveRecord object caching gem using Rails.cache methods.
 
-It makes ActiveRecord 'find_by_id, find_by_(attr)' methods and 'has_one, belongs_to relations' cacheable by id or any referenced columns using Rails.cache methods. It also supports fetching multiple records using ids with find_all_cache method(if cache store supports multiple reads [hint: memcached_store, dalli_store supports.]).
+It makes "ActiveRecord 'find_by_id, find_by_(attr)' methods and 'has_one, belongs_to' relations" cacheable by id or any referenced columns using Rails.cache methods. It also supports fetching multiple records using ids with find_all_cache method(if cache store supports multiple reads [hint: memcached_store, dalli_store supports.]).
 
-## Installation
+== Installation
 
 Add this line to your application's Gemfile:
 
@@ -18,50 +18,44 @@ Or install it yourself as:
 
     $ gem install find_cache
 
-## For has_one and belongs_to relations
+== For has_one and belongs_to relations
 
 ### Sample Models:
 
-User (`has_one :user_detail`) -> 
-
-    find_cache_has_one :user_detail, UserDetail, :user_id
-
-    find_cache_has_one attr_name_or_any_other_name, ModelName, foreign_key
-
-- name
-- email
-- username
-
-UserDetail (`belongs_to :user`) -> 
-
-    find_cache_belongs_to :user, User, :user_id
-
-    find_cache_belongs_to attr_name_or_any_other_name, ModelName, foreign_key
+    class User < ActiveRecord::Base
+      has_one :user_detail
+  
+      # to enable has_one caching
+      find_cache_has_one :user_detail, UserDetail, :user_id 
+    end
 
-- user_id 
-- avatar
-- age
-- sex
-- location
+    class UserDetail < ActiveRecord::Base
+      has_one :user_detail
+  
+      # to enable belongs_to caching
+      find_cache_belongs_to :user, User, :user_id 
+    end
 
-## For finding a record
+== For finding a record
 
     user = User.find_cache(id) # fetches from cache
-    user.user_detail # fetches from cache if 'find_cache_has_one :user_detail, UserDetail, :user_id' added to User model 
+    user.user_detail
+    # fetches from cache if the User model has
+    # 'find_cache_has_one :user_detail, UserDetail, :user_id'
 
     user = User.find_by_id(id) # fetches from DB
     user.user_detail # fetches from DB
 
-## For fetching multiple ids
+== For fetching multiple ids
     
     users = User.find_all_cache([1,2,3,4,5])
     
-## For fetching a record by attribute
+== For fetching a record by attribute
 
     user_detail = UserDetail.find_by_user_id(1) # from db
     user_detail = UserDetail.find_cache_by_ref(:user_id, 1) # from cache store
 
-## For counter_cache 'cache invalidation'
+== For counter_cache 'cache invalidation'
 
 ### Create a ruby file under config/initializers and add the following codes:
 
@@ -85,9 +79,10 @@ UserDetail (`belongs_to :user`) ->
       end
     end
 
-## Notes
+== Notes
 
 If your worker thread does not kill itself after execution you should clean the find_cache_store manually. It can be done simple in ApplicationController of your rails app adding this method as after_filter
+
   after_filter :clear_find_cache_store
 
   def clear_find_cache_store
@@ -96,11 +91,11 @@ If your worker thread does not kill itself after execution you should clean the
 
 Tested with dalli (https://github.com/mperham/dalli).  
 
-## Credits
+== Credits
 
 FindCache is part of http://videofork.com project.
 
-## Contributing
+== Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/lib/find_cache/cacheable.rb

@@ -1,32 +1,59 @@
 # -*- encoding: utf-8 -*-
 module FindCache
+  
+  # = FindCache Cachable
   module Cacheable
     extend ActiveSupport::Concern
     
-    module ClassMethods    
+    module ClassMethods
+      # has_one relational caching with find_cache
+      #
+      # ==== Parameters
+      #
+      # * +attribute+ - The attribute that you wish to name for cache
+      # * +model+ - The Model which data will be retreived for caching
+      # * +foreign_key+ - The FK attribute name in the given Model
+      #
+      # ==== Examples
+      #
+      #   # For User model with user_id FroeignKey in UserDetail model
+      #   find_cache_has_one :user_detail, UserDetail, :user_id
       def find_cache_has_one(attribute, model, foreign_key)
         send :define_method, attribute.to_sym do |*args|
           $find_cache_store[KeyGen.global_cache_key]["#{attribute}_#{model}_#{foreign_key}_#{self.id}"] ||= model.find_cache_by_ref(foreign_key, self.id)
         end
       end
       
+      # belongs_to relational caching with find_cache
+      #
+      # ==== Parameters
+      #
+      # * +attribute+ - The attribute that you wish to name for cache
+      # * +model+ - The Model which data will be retreived for caching
+      # * +foreign_key+ - The FK attribute name of given Model for the current Model
+      #
+      # ==== Examples
+      #
+      #   # In UserDetail model with user_id FroeignKey of User model
+      #   find_cache_belongs_to :user, User, :user_id
       def find_cache_belongs_to(attribute, model, foreign_key)
         send :define_method, attribute.to_sym do |*args|
           $find_cache_store[KeyGen.global_cache_key]["#{attribute}_#{model}_#{foreign_key}_#{self.send(foreign_key.to_sym)}"] ||= model.find_cache(self.send(foreign_key.to_sym))
         end
       end
-    end
-    
-    included do
-      after_commit :expire_find_cache
-      
-      def expire_find_cache
-        key = KeyGen.cache_key(self.class.name, self.id)
-        Rails.cache.delete(key)
-        $find_cache_store[KeyGen.global_cache_key].delete(key)
-      end
 
-      def self.find_cache(id)
+      # To find an Active Record object using find_by_id method
+      # and caching it using Rails.cache methods
+      #
+      # ==== Parameters
+      #
+      # * +id+ - Id for the model
+      #
+      # ==== Examples
+      #
+      #   # Find a User object with id 1 from User model
+      #   User.find_cache(1)  
+      def find_cache(id)
         key = KeyGen.cache_key(name, id)
         $find_cache_store[KeyGen.global_cache_key][key] ||= (
           Rails.cache.fetch(key) do
@@ -35,12 +62,24 @@ module FindCache
         )
       end
 
-      def self.find_cache_by_ref(ref_attr, ref_id)
-        key_ref = KeyGen.cache_key_ref(name, ref_attr, ref_id)
+      # To find an Active Record object using attributes other than
+      # primary key (:id) and caching it using Rails.cache methods
+      #
+      # ==== Parameters
+      #
+      # * +ref_attr+ - Reference attribute which will be looked in table
+      # * +ref_value+ - Value for the given referenced attribute
+      #
+      # ==== Examples
+      #
+      #   # Find an UserDetail object using user_id attribute with value 1
+      #   UserDetail.find_cache_by_ref(:user_id, 1)
+      def find_cache_by_ref(ref_attr, ref_val)
+        key_ref = KeyGen.cache_key_ref(name, ref_attr, ref_val)
         if (id = Rails.cache.read(key_ref))
           find_cache(id)
         else
-          item = send("find_by_#{ref_attr}", "#{ref_id}")
+          item = send("find_by_#{ref_attr}", "#{ref_val}")
           if item
             Rails.cache.write(key_ref, item.id)
             Rails.cache.write(KeyGen.cache_key(name, item.id), item)
@@ -49,10 +88,27 @@ module FindCache
         end
       end
 
-      def self.find_all_cache(ids, order_by = "id DESC")
+
+      # To find all Active Record objects using id list
+      #
+      # ==== Parameters
+      #
+      # * +ids+ - List of ids 
+      # * +order_by+ - optional order direction for results
+      #
+      # ==== Notes
+      #   # Only valid if the Rails.cache store supports read_multi
+      #
+      # ==== Examples
+      #
+      #   # Find users with ids ([21, 1, 2, 19, 43]) from User model
+      #   UserDetail.find_all_cache([21, 1, 2, 19, 43])
+      #   # Find users with ids ([21, 1, 2, 19, 43]) and id ASC
+      #   UserDetail.find_all_cache(([21, 1, 2, 19, 43]), "id ASC")
+      def find_all_cache(ids, order_by = "id DESC")
         all_new_cache = []
         not_in_cache  = []
-        cache_ids = generate_cache_keys(ids)
+        cache_ids = ids.map { |id| KeyGen.cache_key(name, id) }
         all_cache = Rails.cache.read_multi(cache_ids)
         cache_ids.each_with_index do |cache_id, cache_id_index|
           if all_cache[cache_id]
@@ -71,14 +127,16 @@ module FindCache
         all_new_cache.each do |cached_item|
           $find_cache_store[KeyGen.global_cache_key][KeyGen.cache_key(name, cached_item.id)] = cached_item
         end
-      end
-
-      def self.generate_cache_keys(ids)
-        cache_ids = []
-        ids.each do |id|
-          cache_ids << KeyGen.cache_key(name, id)
-        end
-        cache_ids
+      end    
+    end
+    
+    included do
+      after_commit :expire_find_cache
+      
+      def expire_find_cache
+        key = KeyGen.cache_key(self.class.name, self.id)
+        Rails.cache.delete(key)
+        $find_cache_store[KeyGen.global_cache_key].delete(key)
       end
     end
   end

data/lib/find_cache/init.rb

@@ -1,2 +1,3 @@
 # -*- encoding: utf-8 -*-
+# A local cache store for cached objects of Threads
 $find_cache_store = {}

data/lib/find_cache/key_gen.rb

@@ -3,15 +3,48 @@ module FindCache
   class KeyGen
     require "simple_uuid"
     
+    # cache_key generator for model items
+    #
+    # ==== Parameters
+    #
+    # * +model_name+ - The name of the model
+    # * +id+ - Id for the given model
+    #
+    # ==== Examples
+    #
+    #   FindCache::KeyGen.cache_key("User", 1)
     def self.cache_key(model_name, id)
       "#{model_name}/#{id}"
     end
     
+    # cache_key generator for model items with referenced attribute
+    #
+    # ==== Parameters
+    #
+    # * +model_name+ - The name of the model
+    # * +foreign_key_name+ - Name of the foreign_key attribute
+    # * +foreign_key_id+ - Id for the given foreign_key name
+    #
+    # ==== Examples
+    #
+    #   FindCache::KeyGen.cache_key_ref("UserDetail", "user_id", 1)
     def self.cache_key_ref(model_name, foreign_key_name, foreign_key_id)
       "#{model_name}/#{foreign_key_name}-#{foreign_key_id}"
     end
     
-    def self.global_cache_key(clear=false)
+    # cache_key generator for the current thread
+    #
+    # ==== Parameters
+    #
+    # * +clear+ - Boolean value to clean up the current Thread's cache key
+    #
+    # ==== Examples
+    #
+    #   # For generating cache key for the current Thread
+    #   FindCache::KeyGen.global_cache_key
+    #   # For cleaning generated cache key for the current Thread
+    #   FindCache::KeyGen.global_cache_key(true)
+    def self.global_cache_key(clear = false)
       return (Thread.current[:global_cache_key] = nil) if clear
       Thread.current[:global_cache_key] ||= (
         t = SimpleUUID::UUID.new(Time.now).to_i.to_s(16).rjust(32, "0")
@@ -20,6 +53,8 @@ module FindCache
       )
     end
 
+    # Cleaning all caches of the current Thread not the Rails.cache
+    #
     def self.clear_find_cache_store
       $find_cache_store.delete(KeyGen.global_cache_key)
       KeyGen.global_cache_key(true)

data/lib/find_cache/version.rb

@@ -1,4 +1,4 @@
 # -*- encoding: utf-8 -*-
 module FindCache
-  VERSION = "0.1.6"
+  VERSION = "0.1.7"
 end

data/test/dummy/log/test.log

@@ -375,3 +375,54 @@ Connecting to database specified by database.yml
   User Load (0.1ms)  SELECT "users".* FROM "users" WHERE "users"."id" = 9 LIMIT 1
   User Load (0.3ms)  SELECT "users".* FROM "users" LIMIT 1
   Post Load (0.3ms)  SELECT "posts".* FROM "posts" WHERE "posts"."user_id" = 1 LIMIT 1
+Connecting to database specified by database.yml
+  Post Load (0.2ms)  SELECT "posts".* FROM "posts" LIMIT 1
+   (0.1ms)  begin transaction
+  SQL (6.2ms)  INSERT INTO "comments" ("content", "created_at", "post_id", "updated_at") VALUES (?, ?, ?, ?)  [["content", "test content for comment"], ["created_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00], ["post_id", 1], ["updated_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00]]
+  Post Load (0.2ms)  SELECT "posts".* FROM "posts" WHERE "posts"."id" = 1 LIMIT 1
+  SQL (0.2ms)  UPDATE "posts" SET "comments_count" = COALESCE("comments_count", 0) + 1 WHERE "posts"."id" = 1
+   (1.5ms)  commit transaction
+  Post Load (0.2ms)  SELECT "posts".* FROM "posts" WHERE "posts"."id" = 1 LIMIT 1
+  Post Load (0.2ms)  SELECT "posts".* FROM "posts" WHERE "posts"."id" = 1 LIMIT 1
+  Post Load (0.2ms)  SELECT "posts".* FROM "posts" LIMIT 1
+   (0.0ms)  begin transaction
+  SQL (0.4ms)  INSERT INTO "comments" ("content", "created_at", "post_id", "updated_at") VALUES (?, ?, ?, ?)  [["content", "test 1 content for comment"], ["created_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00], ["post_id", 1], ["updated_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00]]
+  Post Load (0.1ms)  SELECT "posts".* FROM "posts" WHERE "posts"."id" = 1 LIMIT 1
+  SQL (0.1ms)  UPDATE "posts" SET "comments_count" = COALESCE("comments_count", 0) + 1 WHERE "posts"."id" = 1
+   (1.6ms)  commit transaction
+  Post Load (0.1ms)  SELECT "posts".* FROM "posts" LIMIT 1
+   (0.0ms)  begin transaction
+  SQL (0.3ms)  INSERT INTO "comments" ("content", "created_at", "post_id", "updated_at") VALUES (?, ?, ?, ?)  [["content", "test 2 content for comment"], ["created_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00], ["post_id", 1], ["updated_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00]]
+  Post Load (0.1ms)  SELECT "posts".* FROM "posts" WHERE "posts"."id" = 1 LIMIT 1
+  SQL (0.1ms)  UPDATE "posts" SET "comments_count" = COALESCE("comments_count", 0) + 1 WHERE "posts"."id" = 1
+   (1.4ms)  commit transaction
+  Post Load (0.1ms)  SELECT "posts".* FROM "posts" LIMIT 1
+   (0.0ms)  begin transaction
+  SQL (0.4ms)  INSERT INTO "comments" ("content", "created_at", "post_id", "updated_at") VALUES (?, ?, ?, ?)  [["content", "test 3 content for comment"], ["created_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00], ["post_id", 1], ["updated_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00]]
+  Post Load (0.1ms)  SELECT "posts".* FROM "posts" WHERE "posts"."id" = 1 LIMIT 1
+  SQL (0.1ms)  UPDATE "posts" SET "comments_count" = COALESCE("comments_count", 0) + 1 WHERE "posts"."id" = 1
+   (1.5ms)  commit transaction
+  Post Load (0.1ms)  SELECT "posts".* FROM "posts" LIMIT 1
+   (0.0ms)  begin transaction
+  SQL (0.3ms)  INSERT INTO "comments" ("content", "created_at", "post_id", "updated_at") VALUES (?, ?, ?, ?)  [["content", "test 4 content for comment"], ["created_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00], ["post_id", 1], ["updated_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00]]
+  Post Load (0.1ms)  SELECT "posts".* FROM "posts" WHERE "posts"."id" = 1 LIMIT 1
+  SQL (0.1ms)  UPDATE "posts" SET "comments_count" = COALESCE("comments_count", 0) + 1 WHERE "posts"."id" = 1
+   (1.8ms)  commit transaction
+  Comment Load (0.3ms)  SELECT "comments".* FROM "comments" WHERE "comments"."id" IN (32, 33, 34, 35) ORDER BY id ASC
+  Comment Load (0.2ms)  SELECT "comments".* FROM "comments" WHERE "comments"."id" IN (32, 33, 34, 35) ORDER BY id ASC
+  Post Load (0.2ms)  SELECT "posts".* FROM "posts" LIMIT 1
+  Post Load (0.1ms)  SELECT "posts".* FROM "posts" WHERE "posts"."id" = 1 LIMIT 1
+   (0.1ms)  begin transaction
+   (0.1ms)  commit transaction
+  Post Load (0.2ms)  SELECT "posts".* FROM "posts" WHERE "posts"."id" = 1 LIMIT 1
+  Post Load (0.3ms)  SELECT "posts".* FROM "posts" LIMIT 1
+  User Load (0.1ms)  SELECT "users".* FROM "users" WHERE "users"."id" = 1 LIMIT 1
+   (0.1ms)  begin transaction
+  SQL (0.6ms)  INSERT INTO "users" ("created_at", "email", "password", "updated_at") VALUES (?, ?, ?, ?)  [["created_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00], ["email", "test@videofork.com"], ["password", "test1234"], ["updated_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00]]
+  SQL (0.4ms)  INSERT INTO "posts" ("body", "comments_count", "created_at", "title", "updated_at", "user_id") VALUES (?, ?, ?, ?, ?, ?)  [["body", nil], ["comments_count", nil], ["created_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00], ["title", nil], ["updated_at", Wed, 29 Aug 2012 18:30:29 UTC +00:00], ["user_id", 10]]
+  Post Load (0.1ms)  SELECT "posts".* FROM "posts" WHERE "posts"."user_id" = 10 LIMIT 1
+   (1.8ms)  commit transaction
+  User Load (0.3ms)  SELECT "users".* FROM "users" WHERE "users"."id" = 10 LIMIT 1
+  User Load (0.1ms)  SELECT "users".* FROM "users" WHERE "users"."id" = 10 LIMIT 1
+  User Load (0.3ms)  SELECT "users".* FROM "users" LIMIT 1
+  Post Load (0.3ms)  SELECT "posts".* FROM "posts" WHERE "posts"."user_id" = 1 LIMIT 1

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: find_cache
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-29 00:00:00.000000000 Z
+date: 2012-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -186,6 +186,7 @@ files:
 - test/dummy/tmp/cache/276/5C0/User%2F9
 - test/dummy/tmp/cache/276/6F0/Post%2F2
 - test/dummy/tmp/cache/277/700/Post%2F3
+- test/dummy/tmp/cache/29E/F20/User%2F10
 - test/dummy/tmp/cache/3A8/070/Comment%2F7
 - test/dummy/tmp/cache/3A9/080/Comment%2F8
 - test/dummy/tmp/cache/3AA/090/Comment%2F9
@@ -197,10 +198,14 @@ files:
 - test/dummy/tmp/cache/3D5/D70/Comment%2F22
 - test/dummy/tmp/cache/3D6/D70/Comment%2F14
 - test/dummy/tmp/cache/3D6/D80/Comment%2F23
+- test/dummy/tmp/cache/3D6/D90/Comment%2F32
 - test/dummy/tmp/cache/3D7/D80/Comment%2F15
 - test/dummy/tmp/cache/3D7/D90/Comment%2F24
+- test/dummy/tmp/cache/3D7/DA0/Comment%2F33
 - test/dummy/tmp/cache/3D8/DA0/Comment%2F25
+- test/dummy/tmp/cache/3D8/DB0/Comment%2F34
 - test/dummy/tmp/cache/3D9/DA0/Comment%2F17
+- test/dummy/tmp/cache/3D9/DC0/Comment%2F35
 - test/dummy/tmp/cache/3DA/DB0/Comment%2F18
 - test/dummy/tmp/cache/3DA/DC0/Comment%2F27
 - test/dummy/tmp/cache/3DB/DC0/Comment%2F19
@@ -292,6 +297,7 @@ test_files:
 - test/dummy/tmp/cache/276/5C0/User%2F9
 - test/dummy/tmp/cache/276/6F0/Post%2F2
 - test/dummy/tmp/cache/277/700/Post%2F3
+- test/dummy/tmp/cache/29E/F20/User%2F10
 - test/dummy/tmp/cache/3A8/070/Comment%2F7
 - test/dummy/tmp/cache/3A9/080/Comment%2F8
 - test/dummy/tmp/cache/3AA/090/Comment%2F9
@@ -303,10 +309,14 @@ test_files:
 - test/dummy/tmp/cache/3D5/D70/Comment%2F22
 - test/dummy/tmp/cache/3D6/D70/Comment%2F14
 - test/dummy/tmp/cache/3D6/D80/Comment%2F23
+- test/dummy/tmp/cache/3D6/D90/Comment%2F32
 - test/dummy/tmp/cache/3D7/D80/Comment%2F15
 - test/dummy/tmp/cache/3D7/D90/Comment%2F24
+- test/dummy/tmp/cache/3D7/DA0/Comment%2F33
 - test/dummy/tmp/cache/3D8/DA0/Comment%2F25
+- test/dummy/tmp/cache/3D8/DB0/Comment%2F34
 - test/dummy/tmp/cache/3D9/DA0/Comment%2F17
+- test/dummy/tmp/cache/3D9/DC0/Comment%2F35
 - test/dummy/tmp/cache/3DA/DB0/Comment%2F18
 - test/dummy/tmp/cache/3DA/DC0/Comment%2F27
 - test/dummy/tmp/cache/3DB/DC0/Comment%2F19