archipelago 0.1.0

data/lib/treasure.rb

@@ -0,0 +1,679 @@
+# Archipelago - a distributed computing toolkit for ruby
+# Copyright (C) 2006  Martin Kihlgren <zond at troja dot ath dot cx>
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+
+require 'drb'
+require 'disco'
+require 'bdb'
+require 'pathname'
+require 'digest/sha1'
+require 'pp'
+require 'set'
+require 'hashish'
+require 'tranny'
+
+module Archipelago
+
+  module Treasure
+    
+    #
+    # Minimum time between trying to recover
+    # crashed transactions.
+    #
+    TRANSACTION_RECOVERY_INTERVAL = 30
+
+    #
+    # Raised whenever the optimistic locking of the serializable transaction isolation level
+    # was proved wrong.
+    #
+    class RollbackException < RuntimeError
+      def initialize(chest, transaction)
+        super("#{chest} has been modified during #{transaction}")
+      end
+    end
+
+    #
+    # Raised whenever a method is called on an object that we dont know about.
+    #
+    class UnknownObjectException < RuntimeError
+      def initialize(chest, key, transaction)
+        super("#{chest} does not contain #{key} under #{transaction}")
+      end
+    end
+
+    #
+    # Raised if a Dubloon or Chest doesnt know what transaction you are talking about.
+    #
+    class UnknownTransactionException < RuntimeError
+      def initialize(source, transaction)
+        super("#{source} is not a part of #{transaction}")
+      end
+    end
+
+    #
+    # Raised if anyone tries to commit a non-prepared transaction.
+    #
+    class IllegalCommitException < RuntimeError
+      def initialize(source, transaction)
+        super("#{transaction} is not prepared in #{source}")
+      end
+    end
+
+    #
+    # Raised if someone tries to join us to a non-active transaction.
+    #
+    class IllegalJoinException < RuntimeError
+      def initialize(transaction)
+        super("#{transaction} is not active")
+      end
+    end
+
+    #
+    # A proxy to something in the chest.
+    #
+    class Dubloon
+      #
+      # Remove all methods so that we look like our target.
+      #
+      instance_methods.each do |method| 
+        undef_method method unless method =~ /^__/
+      end
+      #
+      # Initialize us with knowledge of our +chest+, the +key+ to our
+      # target in the +chest+, the known +public_methods+ of our target
+      # and any +transaction+ we are associated with.
+      #
+      def initialize(key, chest, transaction, chest_id, public_methods)
+        @key = key
+        @chest = chest
+        @transaction = transaction
+        @chest_id = chest_id
+        @public_methods = public_methods
+      end
+      #
+      # The public_methods of our target.
+      #
+      def public_methods
+        return @public_methods.clone
+      end
+      #
+      # Return a clone of myself that is joined to
+      # the +transaction+.
+      #
+      def join(transaction)
+        @chest.join!(transaction) if transaction
+        return Dubloon.new(@key, @chest, transaction, @chest_id, @public_methods)
+      end
+      #
+      # Raises exception if the given +transaction+
+      # is not the same as our own.
+      #
+      def assert_transaction(transaction)
+        raise UnknownTransactionException.new(self, transaction) unless transaction == @transaction
+      end
+      #
+      # The object_id of our chest-held target.
+      #
+      def object_id
+        id = "#{@chest_id}:#{@key}"
+        id << ":#{@transaction.transaction_id}" if @transaction
+        return id
+      end
+      #
+      # Does our target respond to +meth+?
+      #
+      def respond_to?(meth)
+        return @public_methods.include?(meth.to_sym) || @public_methods.include?(meth.to_s)
+      end
+      #
+      # Call +meth+ with +args+ and +block+ on our target if it responds to
+      # it.
+      #
+      def method_missing(meth, *args, &block)
+        if respond_to?(meth)
+          return @chest.call_instance_method(@key, meth, @transaction, *args, &block)
+        else
+          return super(meth, *args)
+        end
+      end
+            
+    end
+
+    #
+    # A possibly remote database that only returns proxies to its
+    # contents, and thus runs all methods on its contents itself.
+    #
+    # Has support for optimistically locked distributed serializable transactions.
+    #
+    # TODO: Test the transaction recovery mechanism.
+    #
+    class Chest
+
+      #
+      # The Chest never leaves its host.
+      #
+      include DRb::DRbUndumped
+
+      #
+      # The Chest can be published.
+      #
+      include Archipelago::Disco::Publishable
+
+      #
+      # Initialize a Chest
+      #
+      # Will use a BerkeleyHashishProvider using treasure_chest.db in the same dir to get its hashes
+      # if not <i>:persistence_provider</i> is given.
+      #
+      # Will try to recover crashed transaction every <i>:transaction_recovery_interval</i> seconds
+      # or TRANSACTION_RECOVERY_INTERVAL if none is given.
+      #
+      # Will use Archipelago::Disco::Publishable by calling <b>initialize_publishable</b> with +options+.
+      #
+      def initialize(options = {})
+        #
+        # The provider of happy magic persistent hashes of different kinds.
+        #
+        @persistence_provider = options[:persistence_provider] || Archipelago::Hashish::BerkeleyHashishProvider.new(Pathname.new(File.expand_path(__FILE__)).parent.join("treasure_chest.db"))
+        
+        #
+        # Use the given options to initialize the publishable
+        # instance variables.
+        #
+        initialize_publishable(options)
+
+        #
+        # [transaction => [key => instance]]
+        # To know what stuff is visible to a transaction.
+        #
+        @snapshot_by_transaction = {}
+        @snapshot_by_transaction.extend(Archipelago::Current::Synchronized)
+
+        #
+        # [transaction => [key => when the key was read/updated/deleted]
+        # To know if a transaction is ok to prepare and commit.
+        #
+        @timestamp_by_key_by_transaction = {}
+
+        #
+        # [transaction => [key => instance]]
+        # To know what transactions were prepared but not
+        # properly finished last run.
+        #
+        @crashed = Set.new
+
+        #
+        # The magical persistent map that defines how we actually 
+        # store our data.
+        #
+        @db = @persistence_provider.get_cached_hashish("db")
+
+        initialize_prepared(options[:transaction_recovery_interval] || TRANSACTION_RECOVERY_INTERVAL)
+
+      end
+
+      #
+      # The transactions active in this Chest.
+      #
+      def active_transactions
+        @snapshot_by_transaction.keys.clone
+      end
+
+      #
+      # Return the contents of this chest using a given +key+ and +transaction+.
+      #
+      def [](key, transaction = nil)
+        join!(transaction)
+
+        instance = ensure_instance_with_transaction(key, transaction)
+        return nil unless instance
+        
+        if Dubloon === instance
+          return instance.join(transaction)
+        else
+          return Dubloon.new(key, DRbObject.new(self), transaction, self.service_id, instance.public_methods)
+        end
+      end
+      
+      #
+      # Delete the value of +key+ within +transaction+.
+      #
+      def delete(key, transaction = nil)
+        join!(transaction)
+
+        rval = nil
+        
+        if transaction
+          #
+          # If we have a transaction we must note that it is deleted in a
+          # separate space for that transaction.
+          #
+          snapshot = @snapshot_by_transaction[transaction]
+          snapshot.synchronize do
+
+            rval = snapshot[key]
+
+            snapshot[key] = :deleted
+            #
+            # Make sure we remember when it was last changed according to our main db.
+            #
+            timestamps = @timestamp_by_key_by_transaction[transaction]
+            timestamps[key] = @db.timestamp(key) unless timestamps.include?(key)
+            
+          end
+        else
+          #
+          # Otherwise just ask our persistence provider to delete it.
+          #
+          @db.delete(key)
+        end
+        
+        rval.freeze
+        
+        return rval
+      end
+
+      #
+      # Put something into this chest with a given +key+, +value+ and
+      # +transaction+.
+      #
+      def []=(key, p1, p2 = nil)
+        if p2
+          value = p2
+          transaction = p1
+        else
+          value = p1
+          transaction = nil
+        end
+
+        return set(key, value, transaction)
+      end
+
+      #
+      # Call an instance +method+ on whatever this chest holds at +key+
+      # with any +transaction+ and +args+.
+      #
+      def call_instance_method(key, method, transaction, *arguments, &block)
+        if transaction
+          return call_with_transaction(key, method, transaction, *arguments, &block)
+        else
+          return call_without_transaction(key, method, *arguments, &block)
+        end
+      end
+
+      #
+      # Abort +transaction+ in this Chest.
+      #
+      def abort!(transaction)
+        assert_transaction(transaction)
+
+        snapshot = @snapshot_by_transaction[transaction]
+        #
+        # Make sure nobody can modify this transaction while we
+        # are aborting it.
+        #
+        snapshot.synchronize do
+          serialized_transaction = Marshal.dump(transaction)
+
+          #
+          # If this transaction was successfully prepared
+          #
+          if @snapshot_by_transaction_db.include?(serialized_transaction)
+            #
+            # Unlock the keys that are part of it.
+            #
+            snapshot.each do |key, value|
+              @db.unlock_on(key)
+            end
+            #
+            # And remove it from persistent storage.
+            #
+            @snapshot_by_transaction_db[serialized_transaction] = nil
+            #
+            # And remove its timestamps from persistent storage.
+            #
+            @timestamp_by_key_by_transaction_db[serialized_transaction] = nil
+          end
+          #
+          # Finally delete it from the snapshots.
+          #
+          @snapshot_by_transaction.delete(transaction)
+          #
+          # And from the timestamps.
+          #
+          @timestamp_by_key_by_transaction.delete(transaction)
+        end
+      end
+
+      #
+      # Prepares +transaction+ in this Chest.
+      #
+      # NB: This will cause any update of the data within
+      # this transaction to block until it is either aborted
+      # or commited!
+      #
+      # TODO: Make us aware about whether transactions have affected us
+      # 'for real' ie check whether the instance before the call
+      # differs from the instance after the call. Preferably
+      # without incurring performance lossage.
+      #
+      def prepare!(transaction)
+        assert_transaction(transaction)
+
+        #
+        # If we dont know about this transaction then it can't very well
+        # affect us.
+        #
+        return :unchanged unless @snapshot_by_transaction.include?(transaction)
+
+        snapshot = @snapshot_by_transaction[transaction]
+        #
+        # Make sure nobody can modify this transaction while we are
+        # preparing it.
+        #
+        snapshot.synchronize do
+
+          #
+          # Remember what locks we acquire so that we can
+          # unlock them in case of failure.
+          #
+          locks = []
+          timestamp_by_key = @timestamp_by_key_by_transaction[transaction]
+          #
+          # Acquire a lock on each key in the transaction
+          #
+          snapshot.each do |key, value|
+            if @db.timestamp(key) == timestamp_by_key[key]
+              @db.lock_on(key)
+              locks << key
+            else
+              locks.each do |key|
+                @db.unlock_on(key)
+              end
+              return :abort
+            end
+          end
+          serialized_transaction = Marshal.dump(transaction)
+          
+          #
+          # Dump its state to persistent storage.
+          #
+          @snapshot_by_transaction_db[serialized_transaction] = Marshal.dump(snapshot)
+          #
+          # And dump its timestamps to persistent storage
+          #
+          @timestamp_by_key_by_transaction_db[serialized_transaction] = Marshal.dump(timestamp_by_key)
+          return :prepared
+        end
+      end
+      
+      #
+      # Commits +transaction+ in this Chest.
+      #
+      # NB: Transaction must be prepared before commit is called.
+      #
+      def commit!(transaction)
+        assert_transaction(transaction)
+        raise IllegalCommitException.new(self, transaction) unless @snapshot_by_transaction_db.include?(Marshal.dump(transaction))
+
+        snapshot = @snapshot_by_transaction[transaction]
+        #
+        # Make sure nobody can modify this transaction while we are
+        # commiting it.
+        #
+        snapshot.synchronize do
+          
+          #
+          # Copy each key and value from our private space to the real space
+          #
+          snapshot.each do |key, value|
+            if value == :deleted
+              @db.delete(key)
+            else
+              @db[key] = value
+            end
+          end
+
+          #
+          # Call abort! to clean up after the transaction.
+          #
+          abort!(transaction)
+          
+        end
+      end
+
+      private
+
+      #
+      # Allocates space for this +transaction+.
+      #
+      # Will also call +transaction+.join to make sure
+      # it is aware of us.
+      #
+      def join!(transaction)
+        if transaction
+          if transaction.state == :active
+            @snapshot_by_transaction.synchronize do
+              unless @snapshot_by_transaction.include?(transaction)
+                @snapshot_by_transaction[transaction] = {}
+                @snapshot_by_transaction[transaction].extend(Archipelago::Current::Synchronized)
+                @timestamp_by_key_by_transaction[transaction] = {}
+                transaction.join(DRbObject.new(self))
+              end
+            end
+          else
+            raise IllegalJoinException.new(transaction)
+          end
+        end
+      end
+
+      #
+      # Raises if we are not in this transaction.
+      #
+      def assert_transaction(transaction)
+        raise UnknownTransactionException.new(self, transaction) unless @snapshot_by_transaction.include?(transaction)
+      end
+
+      #
+      # Call a method within a transaction.
+      #
+      def call_with_transaction(key, method, transaction, *arguments, &block)
+        assert_transaction(transaction)
+
+        #
+        # Fetch our instance from the snapshot.
+        #
+        snapshot = @snapshot_by_transaction[transaction]
+        instance = snapshot[key]
+        instance = nil if instance == :deleted
+
+        raise UnknownObjectException.new(self, key, transaction) unless instance
+
+        begin
+          return execute(instance, method, *arguments, &block)
+        ensure
+          #
+          # Make sure we remember when this object was last changed according
+          # to the main db.
+          #
+          snapshot.synchronize do
+            timestamps = @timestamp_by_key_by_transaction[transaction]
+            timestamps[key] = @db.timestamp(key) unless timestamps.include?(key)
+          end
+        end
+      end
+
+      #
+      # Execute +m+ with arguments +a+ and block +b+ on +o+.
+      #
+      def execute(o, m, *a, &b)
+        if b
+          return o.send(m, *a, &b)
+        else
+          return o.send(m, *a)
+        end
+      end
+
+      #
+      # Call a method outside any transaction (ie inside a transaction of its own).
+      #
+      def call_without_transaction(key, method, *arguments, &block)
+        instance = @db[key]
+
+        raise UnknownObjectException(self, key, transaction) unless instance
+
+        begin
+          return execute(instance, method, *arguments, &block)
+        ensure
+          @db.store_if_changed(key)
+        end
+      end
+
+      #
+      # Initializes our storage of prepared transactions.
+      #
+      def initialize_prepared(transaction_recovery_interval)
+        #
+        # Load stored timestamps for our transaction from db.
+        # 
+        @timestamp_by_key_by_transaction_db = @persistence_provider.get_hashish("prepared_timestamps")
+        @timestamp_by_key_by_transaction_db.each do |serialized_transaction, serialized_timestamps|
+          @timestamp_by_key_by_transaction[Marshal.load(serialized_transaction)] = Marshal.load(serialized_timestamps)
+        end
+
+        #
+        # Load stored snapshots for our transaction from db.
+        #
+        @snapshot_by_transaction_db = @persistence_provider.get_hashish("prepared")
+        @snapshot_by_transaction_db.each do |serialized_transaction, serialized_snapshot|
+          transaction = Marshal.load(transaction)
+
+          @crashed << transaction
+          @snapshot_by_transaction[transaction] = Marshal.load(serialized_snapshot)
+        end
+        start_recovery_thread(transaction_recovery_interval)
+      end
+
+      #
+      # Starts the thread that will keep trying to recover
+      # our crashed transactions.
+      #
+      def start_recovery_thread(transaction_recovery_interval)
+        Thread.new do
+          loop do
+            begin
+              @crashed.clone.each do |transaction|
+                begin
+                  case transaction.state
+                  when :commited
+                    commit!(transaction)
+                    @crashed.delete(transaction)
+                  when :aborted
+                    abort!(transaction)
+                    @crashed.delete(transaction)
+                  end
+                rescue Archipelago::Tranny::UnknownTransactionException => e
+                  abort!(transaction)
+                  @crashed.delete(transaction)
+                end
+              end
+              sleep(transaction_recovery_interval)
+            rescue Exception => e
+              puts e
+              pp e.backtrace
+            end
+          end
+        end
+      end
+
+      #
+      # Insert +value+ under +key+ and +transaction+
+      # in this chest.
+      #
+      def set(key, value, transaction)
+        join!(transaction)
+        value.assert_transaction(transaction) if Dubloon === value
+
+        if transaction
+          snapshot = @snapshot_by_transaction[transaction]
+
+          #
+          # If we have a transaction we must put it in a
+          # separate space for that transaction.
+          #
+          snapshot.synchronize do
+
+            snapshot[key] = value
+            #
+            # Make sure we remember the last time this was changed according to
+            # our main db.
+            #
+            timestamps = @timestamp_by_key_by_transaction[transaction]
+            timestamps[key] = @db.timestamp(key) unless timestamps.include?(key)
+            
+          end
+        else
+          @db[key] = value
+        end
+
+        return value if Dubloon === value
+
+        return Dubloon.new(key, DRbObject.new(self), transaction, service_id, value.public_methods)
+      end
+
+      #
+      # Try to fetch the data of +key+ from the private space
+      # of +transaction+ and put it there if it was not there
+      # already.
+      #
+      def ensure_instance_with_transaction(key, transaction)
+        if transaction
+          snapshot = @snapshot_by_transaction[transaction]
+          snapshot.synchronize do
+
+            #
+            # If we dont have this key in the snapshot.
+            #
+            unless snapshot.include?(key)
+              #
+              # Fetch the new value for the snapshot
+              #
+              new_value = @db.get_deep_clone(key)
+              #
+              # If it exists then copy it to the snapshot
+              # otherwise remove the transaction hash if it is empty.
+              #
+              if new_value
+                snapshot[key] = new_value
+              else
+                @snapshot_by_transaction.delete(transaction) if snapshot.empty?
+              end
+            end
+
+            rval = snapshot[key]
+            return rval == :deleted ? nil : rval
+
+          end
+        else
+          return @db[key]
+        end
+      end
+
+    end
+
+  end
+
+end

data/profiles/1000xChest#join!-prepare!-commit!.rb

@@ -0,0 +1,19 @@
+
+require File.join(File.dirname(__FILE__), 'profile_helper')
+require 'treasure'
+require 'drb'
+
+DRb.start_service
+@c = TestChest.new
+
+k = "hej"
+v = "oj"
+t = TestTransaction.new
+1000.times do |n|
+  @c[k, t] = v
+  @c.prepare!(t)
+  @c.commit!(t)
+end
+
+@c.persistence_provider.unlink
+DRb.stop_service

data/profiles/1000xDubloon#[]=(t).rb

@@ -0,0 +1,19 @@
+
+require File.join(File.dirname(__FILE__), 'profile_helper')
+require 'treasure'
+require 'drb'
+
+DRb.start_service
+@c = TestChest.new
+@tm = TestManager.new
+
+tr = @tm.begin
+k = "hej"
+v = "oj"
+1000.times do |n|
+  @c[k,tr] = v
+end
+
+@c.persistence_provider.unlink
+File.unlink(@tm.db.filename)
+DRb.stop_service