hyperactive 0.1.0

data/lib/hyperactive/record.rb

@@ -0,0 +1,358 @@
+
+require 'rubygems'
+require 'archipelago'
+
+#
+# A utility module to provide the functionality required for example
+# if you want to use archipelago in a Ruby on Rails project *hint hint*.
+#
+module Hyperactive
+
+  #
+  # The default database connector.
+  #
+  CAPTAIN = Archipelago::Pirate::Captain.new
+
+  #
+  # A tiny <b>call</b>able class that saves stuff in
+  # indexes depending on certain attributes.
+  #
+  class IndexBuilder
+    #
+    # Get the first part of the key, that depends on the +attributes+.
+    #
+    def self.get_attribute_key_part(attributes)
+      "Hyperactive::IndexBuilder::#{attributes.join(",")}"
+    end
+    #
+    # Get the last part of the key, that depends on the +values+.
+    #
+    def self.get_value_key_part(values)
+      "#{values.join(",")}"
+    end
+    #
+    # Initialize an IndexBuilder giving it an array of +attributes+
+    # that will be indexed.
+    #
+    def initialize(attributes)
+      @attributes = attributes
+    end
+    #
+    # Get the Tree for the given +record+.
+    #
+    def get_tree_for(record)
+      values = @attributes.collect do |att|
+        if record.respond_to?(att)
+          record.send(att)
+        else
+          nil
+        end
+      end
+      key = "#{self.class.get_attribute_key_part(@attributes)}::#{self.class.get_value_key_part(values)}"
+      return CAPTAIN[key] ||= Tree.get_instance
+    end
+    #
+    # Call this IndexBuilder and pass it a +block+.
+    #
+    # If the +argument+ is an Array then we know we are a save hook, 
+    # otherwise we are a destroy hook.
+    #
+    def call(argument, &block)
+      yield
+
+      #
+      # If the argument is an Array (of old value, new value)
+      # then we are a save hook, otherwise a destroy hook.
+      #
+      if Array === argument
+        record = argument.last
+        old_record = argument.first
+        get_tree_for(old_record).delete(record.record_id)
+        get_tree_for(record)[record.record_id] = record
+      else
+        record = argument
+        get_tree_for(record).delete(record.record_id)
+      end
+    end
+  end
+
+  #
+  # A tiny <b>call</b>able class that saves stuff inside containers
+  # if they match certain criteria.
+  #
+  class MatchSaver
+    #
+    # Initialize this MatchSaver with a +key+, a <b>call</b>able +matcher+
+    # and a +mode+ (:select, :reject, :delete_if_match or :delete_unless_match).
+    #
+    def initialize(key, matcher, mode)
+      @key = key
+      @matcher = matcher
+      @mode = mode
+    end
+    #
+    # Depending on <i>@mode</i> and return value of <i>@matcher</i>.call
+    # may save record in the Hash-like container named <i>@key</i> in
+    # the main database after having yielded to +block+.
+    #
+    def call(argument, &block)
+      yield
+
+      record = argument
+      record = argument.last if Array === argument
+
+      case @mode
+      when :select
+        if @matcher.call(record)
+          CAPTAIN[@key][record.record_id] = record
+        else
+          CAPTAIN[@key].delete(record.record_id)
+        end
+      when :reject
+        if @matcher.call(record)
+          CAPTAIN[@key].delete(record.record_id)
+        else
+          CAPTAIN[@key][record.record_id] = record
+        end
+      when :delete_if_match
+        if @matcher.call(record)
+          CAPTAIN[@key].delete(record.record_id)
+        end
+      when :delete_unless_match
+        unless @matcher.call(record)
+          CAPTAIN[@key].delete(record.record_id)
+        end
+      end
+    end
+  end
+
+  #
+  # A convenient base class to inherit when you want the basic utility methods
+  # provided by for example ActiveRecord::Base *hint hint*.
+  #
+  # NB: After an instance is created, it will actually return a copy <b>within your local machine</b>
+  # which is not what is usually the case. Every other time you fetch it using a select or other
+  # method you will instead receive a proxy object to the database. This means that nothing you
+  # do to it at that point will be persistent or even necessarily have a defined result. 
+  # Therefore: do not use <b>MyRecordSubclass.new</b> to <b>MyRecordSubclass#initialize</b> objects,
+  # instead use <b>MyRecordSubclass.get_instance</b>, since it will return a fresh proxy object
+  # instead of the devious original:
+  #  my_instance = MyRecordSubclass.get_instance(*the_same_arguments_as_to_initialize)
+  #
+  class Record
+
+    @@create_hooks_by_class = {}
+    @@destroy_hooks_by_class = {}
+    @@save_hooks_by_class = {}
+
+    #
+    # The host we are running on.
+    #
+    HOST = "#{Socket::gethostbyname(Socket::gethostname)[0]}" rescue "localhost"
+
+    #
+    # Call this if you want to change the default database connector
+    # to something else.
+    #
+    def self.setup(options = {})
+      CAPTAIN.setup(options[:pirate_options])
+    end
+
+    #
+    # Return our create_hooks, which can then be treated as any old Array.
+    #
+    # These must be <b>call</b>able objects with an arity of 1
+    # that will be sent the instance about to be created (initial
+    # insertion into the database system) that take a block argument.
+    # 
+    # The block argument will be a Proc that actually injects the
+    # instance into the database system.
+    #
+    # Use this to preprocess, validate and/or postprocess your
+    # instances upon creation.
+    #
+    def self.create_hooks
+      self.get_hook_array_by_class(@@create_hooks_by_class)
+    end
+
+    #
+    # Return our destroy_hooks, which can then be treated as any old Array.
+    #
+    # These must be <b>call</b>able objects with an arity of 1
+    # that will be sent the instance about to be destroyed (removal
+    # from the database system) that take a block argument.
+    # 
+    # The block argument will be a Proc that actually removes the
+    # instance from the database system.
+    #
+    # Use this to preprocess, validate and/or postprocess your
+    # instances upon destruction.
+    #
+    def self.destroy_hooks
+      self.get_hook_array_by_class(@@destroy_hooks_by_class)
+    end
+
+    #
+    # Return our save_hooks, which can then be treated as any old Array.
+    #
+    # These must be <b>call</b>able objects with an arity of 1
+    # that will be sent [the old version, the new version] of the 
+    # instance about to be saved (storage into the database system) 
+    # along with a block argument.
+    # 
+    # The block argument will be a Proc that actually saves the
+    # instance into the database system.
+    #
+    # Use this to preprocess, validate and/or postprocess your
+    # instances upon saving.
+    #
+    def self.save_hooks
+      self.get_hook_array_by_class(@@save_hooks_by_class)
+    end
+
+    def self.index_by(*attributes)
+      attribute_key_part = IndexBuilder.get_attribute_key_part(attributes)
+      self.class_eval <<END
+def self.find_by_#{attributes.join("_and_")}(*args)
+    key = "#{attribute_key_part}::" + IndexBuilder.get_value_key_part(args)
+    CAPTAIN[key]
+end
+END
+      index_builder = IndexBuilder.new(attributes)
+      self.save_hooks << index_builder
+      self.destroy_hooks << index_builder
+    end
+    
+    #
+    # Will define a method called +name+ that will include all
+    # existing instances of this class that when sent to +matcher+.call
+    # return true. Will only return instances saved after this selector
+    # is defined.
+    #
+    def self.select(name, matcher)
+      key = self.collection_key(name)
+      CAPTAIN[key] ||= Tree.get_instance
+      self.class_eval <<END
+def self.#{name}
+    CAPTAIN["#{key}"]
+end
+END
+      self.save_hooks << MatchSaver.new(key, matcher, :select)
+      self.destroy_hooks << MatchSaver.new(key, matcher, :delete_if_match)
+    end
+
+    #
+    # Will define a method called +name+ that will include all
+    # existing instances of this class that when sent to +matcher+.call
+    # does not return true. Will only return instances saved after this
+    # rejector is defined.
+    #
+    def self.reject(name, matcher)
+      key = self.collection_key(name)
+      CAPTAIN[key] ||= Tree.get_instance
+      self.class_eval <<END
+def self.#{name}
+    CAPTAIN["#{key}"]
+end
+END
+      self.save_hooks << MatchSaver.new(key, matcher, :reject)
+      self.destroy_hooks << MatchSaver.new(key, matcher, :delete_unless_match)
+    end
+
+    #
+    # Return the record with +record_id+.
+    #
+    def self.find(record_id)
+      CAPTAIN[record_id]
+    end
+    
+    #
+    # Will execute +block+ within a transaction.
+    #
+    def self.transaction(&block)
+      CAPTAIN.transaction(&block)
+    end
+
+    #
+    # Use this method to get new instances of this class, since it will actually 
+    # make sure it both resides in the database and return a proxy to the remote
+    # object.
+    #
+    def self.get_instance(*arguments)
+      instance = self.new(*arguments)
+      instance.instance_eval do
+        @record_id = Digest::SHA1.hexdigest("#{HOST}:#{Time.new.to_f}:#{self.object_id}:#{rand(1 << 32)}")
+      end
+
+      Hyperactive::Hooker.call_with_hooks(instance, *self.create_hooks) do
+        CAPTAIN[instance.record_id] = instance
+      end
+
+      proxy = CAPTAIN[instance.record_id]
+
+      return proxy
+    end
+
+    #
+    # Our semi-unique id.
+    #
+    attr_reader :record_id
+
+    #
+    # This will allow us to wrap any write of us to persistent storage
+    # in the @@save_hooks as long as the Archipelago::Hashish provider
+    # supports it. See Archipelago::Hashish::BerkeleyHashish for an example
+    # of Hashish providers that do this.
+    #
+    def save_hook(old_value, &block)
+      Hyperactive::Hooker.call_with_hooks([old_value, self], *self.class.save_hooks) do
+        yield
+      end
+    end
+
+    #
+    # Remove this instance from the database calling all the right hooks.
+    #
+    # Freezes this instance after having deleted it.
+    #
+    # Returns false without destroying anything if any of the @@pre_destroy_hooks
+    # returns false.
+    #
+    # Returns true otherwise.
+    #
+    def destroy
+      Hyperactive::Hooker.call_with_hooks(self, *self.class.destroy_hooks) do
+        CAPTAIN.delete(@record_id)
+        self.freeze
+      end
+    end
+
+    private
+
+    #
+    # The key used to store the collection with the given +sym+ as name.
+    #
+    def self.collection_key(sym)
+      "Hyperactive::Record::collection_key::#{sym}"
+    end
+
+    #
+    # Get an Array from +hash+ using <i>self</i> as
+    # key. If <i>self</i> doesnt exist in the +hash+
+    # it will recurse by calling the same method in the
+    # superclass until it has been called in Hyperactive::Record.
+    #
+    def self.get_hook_array_by_class(hash)
+      return hash[self] if hash.include?(self)
+
+      if self == Record
+        hash[self] = []
+        return self.get_hook_array_by_class(hash)
+      else
+        hash[self] = self.superclass.get_hook_array_by_class(hash).clone
+        return self.get_hook_array_by_class(hash)
+      end
+    end
+
+  end
+end

data/lib/hyperactive/tree.rb

@@ -0,0 +1,216 @@
+
+require 'rubygems'
+require 'archipelago'
+require 'rbtree'
+
+module Hyperactive
+
+  #
+  # A class suitable for storing large and often-changing datasets in 
+  # an Archipelago environment.
+  #
+  # Is constructed like a set of nested Hashes that automatically create
+  # new children on demand, and will thusly only have to check the path from
+  # the root node to the leaf for changes when method calls return (see Archipelago::Treasure::Chest)
+  # and will only have to actually store into database the leaf itself if it
+  # has changed.
+  #
+  class Tree < Record
+
+    attr_accessor :elements, :subtrees
+
+    WIDTH = 1 << 3
+
+    #
+    # Dont call this! Call <i>Tree.get_instance(options)</i> instead!
+    #
+    def initialize(options = {})
+      @width = options[:width] || WIDTH
+      @elements = {}
+      @subtrees = nil
+    end
+    
+    #
+    # Deletes +key+ in this Tree.
+    #
+    def delete(key)
+      if @elements
+        @elements.delete(key)
+      else
+        subtree_for(key).delete(key)
+      end
+    end
+
+    #
+    # Returns the size of this Tree.
+    #
+    def size
+      if @elements
+        @elements.size
+      else
+        @subtrees.t_collect do |tree_id, tree|
+          tree.size
+        end.inject(0) do |sum, size|
+          sum + size
+        end
+      end
+    end
+    
+    #
+    # Returns all keys and values returning true for +callable+.call(key, value) in this Tree.
+    #
+    def select(callable)
+      if @elements
+        @elements.select do |k,v|
+          callable.call(k,v)
+        end
+      else
+        @subtrees.t_collect do |tree_id, tree|
+          tree.select(callable)
+        end.inject([]) do |sum, match|
+          sum + match
+        end
+      end
+    end
+
+    #
+    # Returns all keys and values returning false for +callable+.call(key, value) in this Tree.
+    #
+    def reject(callable)
+      if @elements
+        @elements.reject do |k,v|
+          callable.call(k,v)
+        end
+      else
+        @subtrees.t_collect do |tree_id, tree|
+          tree.reject(callable)
+        end.inject([]) do |sum, match|
+          sum + match
+        end
+      end
+    end
+
+    #
+    # Puts +value+ under +key+ in this Tree.
+    #
+    def []=(key, value)
+      if @elements
+        if @elements.size < @width
+          @elements[key] = value
+        else
+          split!
+          subtree_for(key)[key] = value
+        end
+      else
+        subtree_for(key)[key] = value
+      end
+      return value
+    end
+
+    #
+    # Returns the value for +key+ in this Tree.
+    #
+    def [](key)
+      if @elements
+        return @elements[key]
+      else
+        return subtree_for(key)[key]
+      end
+    end
+
+    #
+    # Returns an Array containing +callable+.call(key, value) from all values in this Tree.
+    #
+    def collect(callable)
+      rval = []
+      self.each(Proc.new do |k,v|
+                  rval << callable.call(k,v)
+                end)
+      return rval
+    end
+
+    #
+    # Does +callable+.call(key, value) on all values in this Tree.
+    #
+    def each(callable)
+      if @elements
+        @elements.each do |key, value|
+          callable.call(key, value)
+        end
+      else
+        @subtrees.t_each do |tree_id, tree|
+          tree.each(callable)
+        end
+        nil
+      end
+    end
+
+    #
+    # Clear everything from this Tree and destroy it.
+    #
+    def destroy
+      if @elements
+        @elements.each do |key, value|
+          value.destroy if value.respond_to?(:destroy)
+        end
+      else
+        @subtrees.each do |tree_id, tree|
+          tree.destroy
+        end
+      end
+      freeze
+      super
+    end
+
+    #
+    # Clear everything from this Tree.
+    #
+    def clear
+      unless @elements
+        @subtrees.each do |tree_id, tree|
+          tree.clear
+        end
+        @subtrees = nil
+      end
+      @elements = {}
+    end
+
+    private
+
+    #
+    # Finds the subtree responsible for +key+.
+    #
+    # Does it in this ugly way cause the nice way of just doing modulo gave
+    # really odd results since all hashes seem to give some modulo values
+    # a lot more often than expected.
+    #
+    def subtree_for(key)
+      key_id = Digest::SHA1.new("#{key.hash}#{self.record_id}").to_s
+      @subtrees.each do |tree_id, tree|
+        return tree if tree_id > key_id
+      end
+      return @subtrees.values.first
+    end
+
+    #
+    # Split this Tree by creating @subtrees,
+    # then putting all @elements in them and then emptying @elements.
+    #
+    def split!
+      raise "Cant split twice!" unless @elements
+
+      @subtrees = RBTree.new
+      @subtrees.extend(Archipelago::Current::ThreadedCollection)
+      step = (1 << 160) / @width
+      0.upto(@width - 1) do |n|
+        @subtrees["%x" % (n * step)] = Tree.get_instance(:width => @width)
+      end
+      @elements.each do |key, value|
+        subtree_for(key)[key] = value
+      end
+      @elements = nil
+    end
+
+  end
+
+end

data/lib/hyperactive.rb

@@ -0,0 +1,6 @@
+
+$: << File.dirname(__FILE__)
+
+require 'hyperactive/hooker'
+require 'hyperactive/record'
+require 'hyperactive/tree'