cuboid 0.0.0 → 0.0.1alpha

data/lib/cuboid/state/options.rb

@@ -0,0 +1,27 @@
+module Cuboid
+class State
+
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Options
+
+    def statistics
+        {}
+    end
+
+    def dump( directory )
+        FileUtils.mkdir_p( directory )
+        Cuboid::Options.save( "#{directory}/options" )
+    end
+
+    def self.load( directory )
+        Cuboid::Options.load( "#{directory}/options" )
+        new
+    end
+
+    def clear
+    end
+
+end
+
+end
+end

data/lib/cuboid/support.rb

@@ -0,0 +1,11 @@
+module Cuboid::Support
+end
+
+lib = Cuboid::Options.paths.support
+require lib + 'mixins'
+require lib + 'buffer'
+require lib + 'cache'
+require lib + 'crypto'
+require lib + 'database'
+require lib + 'filter'
+require lib + 'glob'

data/lib/cuboid/support/buffer.rb

@@ -0,0 +1,3 @@
+buffers = Cuboid::Options.paths.support + 'buffer/'
+require buffers + 'base'
+require buffers + 'autoflush'

data/lib/cuboid/support/buffer/autoflush.rb

@@ -0,0 +1,61 @@
+module Cuboid
+module Support::Buffer
+
+# A buffer implementation which flushes itself when it gets full or a number
+# of push attempts is reached between flushes.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class AutoFlush < Base
+
+    attr_reader :max_pushes
+
+    # @param    [Integer]  max_size
+    #   Maximum buffer size -- a flush will be triggered when that limit is
+    #   reached.
+    # @param    [Integer]  max_pushes
+    #   Maximum number of pushes between flushes.
+    # @param    [#<<, #|, #clear, #size, #empty?]   type
+    #   Internal storage class to use.
+    def initialize( max_size = nil, max_pushes = nil, type = Array )
+        super( max_size, type )
+
+        @max_pushes = max_pushes
+        @pushes     = 0
+    end
+
+    def <<( *args )
+        super( *args )
+    ensure
+        handle_push
+    end
+
+    def batch_push( *args )
+        super( *args )
+    ensure
+        handle_push
+    end
+
+    def flush
+        super
+    ensure
+        @pushes = 0
+    end
+
+    private
+
+    def handle_push
+        @pushes += 1
+        flush if flush?
+    end
+
+    def flush?
+        !!(full? || push_limit_reached?)
+    end
+
+    def push_limit_reached?
+        max_pushes && @pushes >= max_pushes
+    end
+
+end
+end
+end

data/lib/cuboid/support/buffer/base.rb

@@ -0,0 +1,91 @@
+module Cuboid
+module Support::Buffer
+
+#
+# Base buffer class to be extended by more specialised implementation.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+#
+class Base
+    include Support::Mixins::Observable
+
+    # @!method on_push( &block )
+    #   @param    [Block] block   block to call on {#push}
+    advertise :on_push
+
+    # @!method on_batch_push( &block )
+    #   @param    [Block] block   block to call on {#batch_push}
+    advertise :on_batch_push
+
+    # @!method on_flush( &block )
+    #   @param    [Block] block   block to call on {#flush}
+    advertise :on_flush
+
+    # @return   [Integer]   Maximum buffer size.
+    attr_reader :max_size
+
+    # @param    [Integer]  max_size
+    #   Maximum buffer size -- won't be enforced.
+    # @param    [#<<, #|, #clear, #size, #empty?]   type
+    #   Internal storage class to use.
+    def initialize( max_size = nil, type = Array )
+        super()
+        @buffer    = type.new
+        @max_size  = max_size
+    end
+
+    # @note Calls {#on_push} blocks with the given object and pushes an object
+    #   to the buffer.
+    #
+    # @param    [Object]    obj
+    #   Object to push.
+    def <<( obj )
+        notify_on_push obj
+        @buffer << obj
+        self
+    end
+    alias :push :<<
+
+    # @note Calls {#on_batch_push} blocks with the given list and merges the
+    #   buffer with the contents of a list.
+    #
+    # @param    [#|]    list
+    #   List of objects
+    def batch_push( list )
+        notify_on_batch_push list
+        @buffer |= list
+        self
+    end
+
+    # @return   [Integer]
+    #   Number of object in the buffer.
+    def size
+        @buffer.size
+    end
+
+    # @return   [Bool]
+    #   `true` if the buffer is empty, `false` otherwise.
+    def empty?
+        @buffer.empty?
+    end
+
+    # @return   [Bool]
+    #   `true` if the buffer is full, `false` otherwise.
+    def full?
+        !!(max_size && size >= max_size)
+    end
+
+    # @note Calls {#on_flush} blocks with the buffer and then empties it.
+    #
+    # @return   current buffer
+    def flush
+        buffer = @buffer.dup
+        notify_on_flush buffer
+        buffer
+    ensure
+        @buffer.clear
+    end
+
+end
+end
+end

data/lib/cuboid/support/cache.rb

@@ -0,0 +1,7 @@
+lib = Cuboid::Options.paths.support + 'cache/'
+require lib + 'base'
+require lib + 'least_recently_pushed'
+require lib + 'least_recently_used'
+require lib + 'random_replacement'
+require lib + 'least_cost_replacement'
+require lib + 'preference'

data/lib/cuboid/support/cache/base.rb

@@ -0,0 +1,226 @@
+module Cuboid
+module Support::Cache
+
+# Base cache implementation -- stores, retrieves and removes entries.
+#
+# The cache will be pruned (call {#prune}) upon storage operations, removing
+# old entries to make room for new ones.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+# @abstract
+class Base
+    include Support::Mixins::Profiler
+
+    # @return    [Integer]
+    #   Maximum cache size.
+    attr_reader :max_size
+
+    # @param    [Hash]  options
+    # @option   options [Integer, nil]    :size
+    #   Maximum size of the cache (must be > 0, `nil` means unlimited).
+    #   Once the size of the cache is about to exceed `max_size`, the pruning
+    #   phase will be initiated.
+    # # @option   options [true, false]    :freeze    (true)
+    #   Whether or not to freeze stored items.
+    def initialize( options = {} )
+        super()
+
+        @options      = options
+        @freeze       = @options[:freeze].nil? ? true : @options[:freeze]
+        self.max_size = @options[:size]
+
+        @cache    = {}
+        @hits     = 0
+        @misses   = 0
+        @prunings = 0
+    end
+
+    def statistics
+        lookups = @hits + @misses
+
+        {
+            lookups:    lookups,
+            hits:       @hits,
+            hit_ratio:  @hits   == 0 ? 0.0 : @hits   / Float( lookups ),
+            misses:     @misses,
+            miss_ratio: @misses == 0 ? 0.0 : @misses / Float( lookups ),
+            prunings:   @prunings,
+            size:       size,
+            max_size:   max_size
+        }
+    end
+
+    def max_size=( max )
+        @max_size = if !max
+            nil
+        else
+            fail( 'Maximum size must be greater than 0.' ) if max <= 0
+            max
+        end
+    end
+
+    # @return   [Bool]
+    #   `true` is there is no size limit, `false` otherwise
+    def uncapped?
+        !capped?
+    end
+
+    # @return   [Bool]
+    #   `true` is there is a size limit, `false`` otherwise
+    def capped?
+        !!max_size
+    end
+
+    # Uncaps the cache {#max_size} limit
+    def uncap
+        @max_size = nil
+    end
+
+    # @return   [Integer]
+    #   Number of entries in the cache.
+    def size
+        @cache.size
+    end
+
+    # Storage method.
+    #
+    # @param    [Object]    k
+    #   Entry key.
+    # @param    [Object]    v
+    #   Object to store.
+    #
+    # @return   [Object]    `v`
+    def store( k, v )
+        store_with_internal_key( make_key( k ), v )
+    end
+
+    # @see #store
+    def []=( k, v )
+        store( k, v )
+    end
+
+    # Retrieving method.
+    #
+    # @param    [Object]    k
+    #   Entry key.
+    #
+    # @return   [Object, nil]
+    #   Value for key `k`, `nil` if there is no key `k`.
+    def []( k )
+        get_with_internal_key( make_key( k ) )
+    end
+
+    # @note If key `k` exists, its corresponding value will be returned.
+    #   If not, the return value of `block` will be assigned to key `k` and that
+    #   value will be returned.
+    #
+    # @param    [Object]    k
+    #   Entry key.
+    #
+    # @return   [Object]
+    #   Value for key `k` or `block.call` if key `k` does not exist.
+    def fetch( k, &block )
+        k = make_key( k )
+
+        if @cache.include?( k )
+            get_with_internal_key( k )
+        else
+            @misses += 1
+            store_with_internal_key( k, profile_proc( &block ) )
+        end
+    end
+
+    # @return   [Bool]
+    #   `true` if cache includes an entry for key `k`, false otherwise.
+    def include?( k )
+        @cache.include?( make_key( k ) )
+    end
+
+    # @return   [Bool]
+    #   `true` if cache is empty, false otherwise.
+    def empty?
+        @cache.empty?
+    end
+
+    # @return   [Bool]
+    #   `true` if cache is not empty, `false` otherwise.
+    def any?
+        !empty?
+    end
+
+    # Removes entry with key `k` from the cache.
+    #
+    # @param    [Object]    k
+    #   Key.
+    #
+    # @return   [Object, nil]
+    #   Value for key `k`, `nil` if there is no key `k`.
+    def delete( k )
+        @cache.delete( make_key( k ) )
+    end
+
+    # Clears/empties the cache.
+    def clear
+        @cache.clear
+    end
+
+    def ==( other )
+        hash == other.hash
+    end
+
+    def hash
+        @cache.hash
+    end
+
+    def dup
+        self.class.new( @options.dup ).tap { |h| h.cache = @cache.dup }
+    end
+
+    protected
+
+    def cache=( c )
+        @cache = c
+    end
+
+    private
+
+    def store_with_internal_key( k, v )
+        while capped? && (size > max_size - 1)
+            prune
+            @prunings += 1
+        end
+
+        _store( k, v )
+    end
+
+    def _store( k, v )
+        @cache[k] = @freeze ? v.freeze : v
+    end
+
+    def get_with_internal_key( k )
+        if (r = @cache[k])
+            @hits += 1
+        else
+            @misses += 1
+        end
+        r
+    end
+
+    def make_key( k )
+        k.hash
+    end
+
+    def cache
+        @cache
+    end
+
+    # Called to make room when the cache is about to reach its maximum size.
+    #
+    # @abstract
+    def prune
+        fail NotImplementedError
+    end
+
+end
+end
+end

data/lib/cuboid/support/cache/least_cost_replacement.rb

@@ -0,0 +1,77 @@
+module Cuboid
+module Support::Cache
+
+# Least Cost Replacement cache implementation.
+#
+# Maintains 3 cost classes (low, medium, high) ) and discards entries from the
+# lowest cost classes in order to make room for new ones.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class LeastCostReplacement < Base
+
+    VALID_COSTS = [ :low, :medium, :high ]
+
+    # @see Cuboid::Cache::Base#initialize
+    def initialize( * )
+        super
+        reset_costs
+    end
+
+    # Storage method
+    #
+    # @param    [Object]    k
+    #   Entry key.
+    # @param    [Object]    v
+    #   Object to store.
+    # @param    [Symbol]    cost
+    #
+    # @return   [Object]    `v`
+    #
+    # @see VALID_COSTS
+    def store( k, v, cost = :low )
+        fail( "invalid cost: #{cost}" ) if !valid_cost?( cost )
+
+        super( k, v )
+    ensure
+        @costs[cost] << k
+    end
+
+    # @see Cuboid::Cache::Base#clear
+    def clear
+        super
+    ensure
+        reset_costs
+    end
+
+    private
+
+    def reset_costs
+        @costs = {}
+        VALID_COSTS.each { |c| @costs[c] = [] }
+    end
+
+    def valid_cost?( cost )
+        VALID_COSTS.include?( cost )
+    end
+
+    def candidate_from_cost_class( cost_class )
+        return if (costs = @costs[cost_class]).empty?
+        costs.delete_at( rand( costs.size ) )
+    end
+
+    def prune_candidate
+        VALID_COSTS.each do |cost|
+            if c = candidate_from_cost_class( cost )
+                return c
+            end
+        end
+    end
+
+    def prune
+        delete( prune_candidate )
+    end
+
+end
+
+end
+end