unicache 0.0.1

data/lib/unicache.rb

@@ -0,0 +1,498 @@
+# UniCache is Universal purpose Cache with Least Recently Used
+# replacement policy by default. Cache can be configured with another
+# policy.
+#
+# UniCache is intended to be Thread safe.
+#
+# User can register callbacks that are run at various UniCache events.
+# ":getdata" callback is used to retreive cache data if not in
+# cache. Others do not effect the UniCache state.
+#
+# Usage example:
+#   require 'unicache'
+#
+#   # Create cache with size 2.
+#   c = UniCache.new( 2 )
+# 
+#   # Register callbacks for some events (two for hit).
+#   c.registerCallback( :hit, Proc.new{ |k,v| puts  "Hit:   #{k}:#{v}" } )
+#   c.registerCallback( :hit, Proc.new{ |k,v| puts  "Found: #{k}:#{v}" } )
+#   c.registerCallback( :miss, Proc.new{ |k,v| puts "Miss:  #{k}:<NA>" } )
+#
+#   # Set some values.
+#   c[0] = 'foo'   # set 0 as 'foo'
+#   c.put( 'bar', 'foo' )
+#
+#   # Get (or try to get) some values.
+#   a = c[ 'bar' ] # hit, a == 'foo'
+#   b = c.get( 0 ) # hit, b == 'foo'
+#   c.get( 'foo' ) # miss
+#   c.get( 2 )     # miss
+#
+# Produces:
+#   Hit:   bar:foo
+#   Found: bar:foo
+#   Hit:   0:foo
+#   Found: 0:foo
+#   Miss:  foo:<NA>
+#   Miss:  2:<NA>
+
+class UniCache < Hash
+
+    # Generic UniCache exception.
+    class Error < StandardError; end
+
+    # ":getdata" callback data fetch exception.
+    class FetchError < Error; end
+
+    # Entry remove error.
+    class RemoveError < Error; end
+
+    # Callback error.
+    class CallbackError < Error; end
+
+    # Sizing error.
+    class SizeError < Error; end
+
+
+    # Cache size.
+    attr_reader :size
+
+    # Access lock.
+    attr_reader :lock
+
+    # Cache initialization.
+    #
+    # @param size [Integer] Cache size.
+    # @param evict [Object] Eviction policy.
+    def initialize( size, evict = LruEviction.new )
+        super()
+
+        @lock = Mutex.new
+
+        resize( size )
+
+        setEviction( evict )
+
+        # See: registerCallback.
+        @callbacks = {}
+
+        @callbackType = [ :getdata,
+                          :add, :replace, :put, :overwrite,
+                          :remove, :valueremove, :hit, :miss,
+                          :peek ]
+        
+        @callbackType.each do |type|
+            @callbacks[ type ] = []
+        end
+
+    end
+
+
+    # Set the eviction policy.
+    #
+    # @param evict [Object] Cache eviction policy.
+    def setEviction( evict )
+        @evict = evict
+    end
+
+
+    alias :hash_set_op :[]=
+    alias :hash_get_op :[]
+
+    alias :hash_store :store
+    alias :hash_fetch :fetch
+
+    alias :hash_delete :delete
+
+
+    # Disable Hash manipulate methods:
+    [ :merge, :merge!, :delete_if, :replace, :keep_if,
+      :reject, :update, :shift ].each do |method|
+        define_method( method ) {}
+        undef_method method
+    end
+
+    # Dummy definition for "store" just for removal.
+    def store(); end
+    
+    # Remove "store" from UniCache.
+    remove_method :store
+
+
+    # Put new entry to the Cache. Make space for the new entry if
+    # needed.
+    #
+    # @param key [Object] Key (or tag) of the Cache entry.
+    # @param value [Object] Value of the Cache entry.
+    def put( key, value )
+        @lock.lock
+        ret = _put( key, value )
+        @lock.unlock
+        ret 
+    end
+
+
+    # Put operator.
+    def []=( key, value )
+        self.put( key, value )
+    end
+
+
+    # Get Cache entry by key or return nil if not in Cache.
+    #
+    # If block is provided, it is run under UniCache lock and will
+    # protect the used data from being removed (concurrently).
+    #
+    # If ":getdata" callback is defined, it is used to get data. Data
+    # is always used, also when nil. UniCache lock is released before
+    # callback is called.
+    #
+    # @param key [Object] Key (or tag) of the Cache entry.
+    # @yield Procedure to fetch the data.
+    def get( key, &blk )
+        @lock.lock
+        ret = _get( key, &blk )
+        @lock.unlock
+        ret 
+    end
+
+
+    # Get operator.
+    def []( key )
+        get( key )
+    end
+
+
+    # Get Cache entry by key (no effect to eviction).
+    #
+    # @param key [Object] Entry key or tag.
+    def peek( key )
+        runCallbacks( :peek, key )
+        hash_fetch( key, nil )
+    end
+
+
+    # Get Cache entry existance by key (no effect to eviction). Uses
+    # "peek", i.e. peek CB is run.
+    #
+    # @param key [Object] Entry key or tag.
+    def exist?( key )
+        if peek( key )
+            true
+        else
+            false
+        end
+    end
+
+
+    # Remove oldest Cache entry (Least Recently Used) or given.
+    #
+    # @param key [Object] Key to remove.
+    # @return [Object, Object] Key/value pair removed or nil if no entries.
+    def remove( key = nil )
+        @lock.lock
+        ret = _remove( key )
+        @lock.unlock
+        ret
+    end
+
+
+    # Resize the Cache.
+    #
+    # @param size [Integer] New Cache size.
+    def resize( size )
+        
+        raise SizeError, "UniCache: Size must be bigger than 0" unless size > 0
+
+        @lock.lock
+
+        # Remove entries that does not fit anymore.
+        if @size && size < @size
+            ( @size - size ).times do
+                _remove
+            end
+        end
+
+        ret = @size = size
+
+        @lock.unlock
+
+        ret
+    end
+
+
+    # Register a callback to be executed on Cache event.
+    #
+    # Possible events:
+    #
+    # [getdata]  Data not found in cache, callback is used to fetch
+    #            it. Data is always added to cache unless an exception
+    #            is raised. Also all retrys should be captured into
+    #            ":getdata". <key,value> from request.
+    #
+    # [add]  Item is added to Cache without anything being
+    #        replaced. <key,value> from request.
+    #
+    # [replace]  Item is added to Cache and another item is
+    #            removed. <key,value> is evicted entry.
+    #
+    # [put]  Item is added to Cache. Cache conditions has no effect
+    #        i.e. always run for "put". <key,value> from request.
+    #
+    # [overwrite]  Existing entry value is replaced by new item
+    #              value. <key,value> from request.
+    #
+    # [remove]  Entry is deleted from Cache.
+    #
+    # [valueremove]  Entry value is removed (remove or overwrite).
+    #                <key,value> from old entry.
+    #
+    # [hit]  Entry is found in Cache. <key,value> from cache.
+    #
+    # [miss]  Entry is not found in Cache. <key> from request.
+    #
+    # [peek]  Cache peek. <key,value> from request.
+    #
+    # Example:
+    #   registerCallback( :add,
+    #     Proc.new do |k,v,o| puts "Key: #{k} with value #{v} added" end
+    #
+    # @param type [Symbol] Callback event.
+    # @param proc [Proc] Callback called with args: <key>, <value>, <self>.
+    def registerCallback( type, proc )
+        if proc.kind_of?( Proc ) && @callbackType.index( type )
+            @callbacks[ type ].push proc
+        else
+            raise CallbackError, "UniCache: Trying to register invalid callback..."
+        end
+    end
+
+
+    # Remove all callbacks for type or all.
+    #
+    # @param type [Symbol] Remove callback by type.
+    def removeCallback( type = nil )
+        if type
+            @callbacks[ type ] = []
+        else
+            @callbackType.each do |type|
+                @callbacks[ type ] = []
+            end
+        end
+    end
+
+
+    # Clear all Cache entries.
+    def clear
+        @lock.lock
+        self.each do |k,v|
+            removeEntry( k )
+        end
+        @evict.clear
+        @lock.unlock
+    end
+
+
+
+
+    # LeastRecentlyUsed eviction policy. Mutex should be used to
+    # ensure atomicity of operations.
+    #
+    # Eviction policy class should include methods:
+    # [update] Called when key is accessed (get/put).
+    # [remove] Called when key is removed.
+    # [nextEvict] Peek to what is going to be removed next.
+    # [clear] Reset eviction state.
+    class LruEviction
+
+
+        # Instantiate.
+        def initialize
+            @lock = Mutex.new
+            clear
+        end
+
+
+        # Clear eviction list.
+        def clear
+            @lock.lock
+            @list = []
+            @lock.unlock
+        end
+
+
+        # Keep track of the least recently used keys. Place oldest at
+        # the beginning of the list.
+        #
+        # @param key [Object] 
+        def update( key )
+
+            @lock.lock
+
+            # Delete old entries of this key.
+            @list.delete_if do |i| i == key end
+            
+            # Add to end of LRU.
+            @list.push key
+
+            @lock.unlock
+        end
+
+
+        # Remove oldest entry.
+        #
+        # @param key [Object] If given, remove this entry instead of oldest.
+        def remove( key = nil )
+            @lock.lock
+
+            res = nil
+
+            if key
+                @list.delete_if do |i| i == key end
+                res = key
+            else
+                res = @list.shift
+            end
+
+            @lock.unlock
+
+            res
+        end
+
+
+        # Return the oldest i.e. next to be evicted.
+        def nextEvict
+            @list[0]
+        end
+
+    end
+
+
+
+    private
+    
+    
+    def _put( key, value )
+        runAdd = false
+
+        if hash_fetch( key, nil )
+
+            # Entry exists already.
+            runCallbacks( :overwrite, key, value )
+            runCallbacks( :valueremove, key )
+
+        elsif self.length >= @size
+
+            # Overflow.
+            runCallbacks( :replace, @evict.nextEvict )
+            _remove
+
+        else
+
+            # Delay add callback to have the entry value set.
+            runAdd = true
+
+        end
+
+        @evict.update( key )
+
+        hash_store( key, value )
+        
+        runCallbacks( :add, key ) if runAdd
+        runCallbacks( :put, key )
+
+        self
+    end
+    
+
+    def _get( key, &blk )
+
+        ret = hash_fetch( key, nil )
+
+        if ret
+
+            @evict.update( key )
+            runCallbacks( :hit, key )
+
+        else
+
+            runCallbacks( :miss, key, nil )
+
+            unless @callbacks[ :getdata ].empty?
+
+                # Get value using callback.
+
+                @lock.unlock if @lock.locked?
+                ret = runCallbacks( :getdata, key, nil )
+                @lock.lock
+                _put( key, ret )
+
+            end
+
+        end
+
+        if block_given?
+
+            # Get value using block.
+            yield( ret )
+
+        else
+
+            ret
+
+        end
+
+
+    end
+
+
+    def _remove( key = nil )
+        
+        if key
+            unless keys.index( key )
+                @lock.unlock if @lock.locked?
+                raise RemoveError, "Key \"#{key}\" does not exist..." 
+            end
+        else
+            key = @evict.remove
+        end
+
+        value = removeEntry( key )
+        
+        [ key, value ]
+    end
+
+
+    # Remove entry from Cache.
+    def removeEntry( key )
+        if hash_fetch( key, nil )
+            runCallbacks( :remove, key )
+            runCallbacks( :valueremove, key )
+            value = hash_delete( key )
+        else
+            nil
+        end
+    end
+
+
+    # Run all callbacks per type.
+    def runCallbacks( type, key, value = nil )
+        ret = nil
+        @callbacks[ type ].each do |i|
+            ret = callback( i, key, value )
+        end
+        ret
+    end
+
+
+    # Run given callback.
+    def callback( cb, key, value = nil )
+        unless value
+            value = hash_fetch( key, nil )
+        end
+        cb.call( key, value, self ) if cb
+    end
+
+
+end