archipelago 0.1.0

data/lib/tranny.rb

@@ -0,0 +1,650 @@
+# 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 'bdb'
+require 'pathname'
+require 'drb'
+require 'current'
+require 'digest/sha1'
+require 'disco'
+
+module Archipelago
+
+  module Tranny
+
+    #
+    # Time before any Transaction will be automatically aborted.
+    #
+    TRANSACTION_TIMEOUT = 60 * 60
+
+    #
+    # If a member tries to join a transaction that it has allready joined
+    # it will receive this.
+    #
+    class JoinCountException < RuntimeError
+      def initialize(member, transaction)
+        super("#{member.inspect} has allready joined the transaction #{transaction.inspect}")
+      end
+    end
+
+    #
+    # If a member tries to commit a transaction not in :active state
+    # or abort a transaction in :commited state, or any other grave
+    # state offence
+    #
+    class IllegalOperationException < RuntimeError
+      def initialize(operation, transaction)
+        super("#{operation.inspect} is illegal for #{transaction.inspect}")
+      end
+    end
+
+    #
+    # If a member tries to get a transaction that the manager doesnt know about
+    # it gets this.
+    #
+    class UnknownTransactionException < RuntimeError
+      def initialize(transaction_id, manager)
+        super("#{manager.inspect} doesnt know about any transaction with id #{transaction_id.inspect}")
+      end
+    end
+
+    #
+    # If a member tries to report its state and the manager doesnt know about the
+    # member, it gets this.
+    #
+    class UnknownMemberException < RuntimeError
+      def initialize(member, transaction)
+        super("#{transaction.inspect} doesnt know about any member like #{member.inspect}")
+      end
+    end
+
+    #
+    # If a member misbehaves (or the Transaction is completely fucked up) this will be raised
+    #
+    class IllegalStateException < RuntimeError
+      def initialize(transaction)
+        super("#{transaction.inspect} is in a completely fucked up state")
+      end
+    end
+
+    #
+    # The manager itself.
+    #
+    # This will be the drb exported object that participants talk to,
+    # either directly or through a TransactionProxy.
+    #
+    # See also the TransactionProxy and Transaction classes.
+    #
+    class Manager
+
+      include DRb::DRbUndumped
+      include Archipelago::Disco::Publishable
+
+      attr_accessor :error_logger
+      attr_accessor :transaction_timeout
+
+      #
+      # Will use a BerkeleyHashishProvider using tranny_manager.db in the same dir to get its hashes
+      # if not <i>:persistence_provider</i> is given.
+      #
+      # Will create Transactions timing out after <i>:transaction_timeout</i> seconds or TRANSACTION_TIMEOUT
+      # if none is given.
+      #
+      # Will use Archipelago::Disco::Publishable by calling <b>initialize_publishable</b> with +options+.
+      #
+      def initialize(options = {})
+        @persistence_provider = options[:persistence_provider] || Archipelago::Hashish::BerkeleyHashishProvider.new(Pathname.new(File.expand_path(__FILE__)).parent.join("tranny_manager.db"))
+
+        initialize_publishable(options)
+
+        @transaction_timeout = options[:transaction_timeout] || TRANSACTION_TIMEOUT
+
+        @metadata = @persistence_provider.get_hashish("metadata")
+        @db = @persistence_provider.get_cached_hashish("db")
+      end
+      
+      #
+      # Returns a proxy to a newly created Transaction.
+      #
+      # The Transaction will timeout after <i>:timeout</i> seconds
+      # or @transaction_timeout if none is given.
+      #
+      def begin(options = {})
+        options[:manager] = self
+        options[:timeout] ||= @transaction_timeout
+        return Transaction.new(options).proxy
+      end
+
+      #
+      # Used by transactions to notify this manager
+      # about an error. Delegates the actual logging
+      # to @error_logger.call(exception).
+      #
+      # Set @error_logger or override this method
+      # if you want to log any errors.
+      #
+      def log_error(exception)
+        self.error_logger.call(exception) if self.error_logger
+      end
+
+      #
+      # Used by a +transaction+ to store its state for future reference.
+      #
+      def store_transaction!(transaction)
+        @db[transaction.transaction_id] = transaction
+      end
+
+      #
+      # Used by a +transaction+ to remove its state when finished.
+      #
+      def remove_transaction!(transaction)
+        @db.delete(transaction.transaction_id)
+      end
+
+      #
+      # Used by a transaction proxy to run +meth+ with +args+ on its +transaction_id+.
+      #
+      def call_instance_method(transaction_id, meth, *args)
+        transaction = @db[transaction_id]
+        if transaction
+          return transaction.send(meth, *args)
+        else
+          raise UnknownTransactionException.new(transaction_id, self)
+        end
+      end
+
+    end
+    
+
+
+
+    #
+    # A proxy to a transaction managed by this manager.
+    #
+    # Used because standard DRbObjects only use object_id
+    # to identify objects, while we want the more unique transaction_id.
+    #
+    # Will also remember the state of the transaction when it detects
+    # methods that will terminate it (:commit | :abort).
+    #
+    class TransactionProxy
+      attr_accessor :transaction_id
+      def initialize(transaction)
+        @manager = transaction.manager
+        @transaction_id = transaction.transaction_id
+        @state = :unknown
+      end
+      #
+      # Return the cached state of the wrapped Archipelago::Tranny::Transaction
+      # if it is known, otherwise fetch it.
+      #
+      def state
+        if @state == :unknown
+          method_missing(:state)
+        else
+          @state
+        end
+      end
+      #
+      # Implemented to ensure that all TransactionProxies with the same
+      # transaction_id are hashwise equal.
+      #
+      def hash
+        @transaction_id.hash
+      end
+      #
+      # Implemented to ensure that all TransactionProxies with the same
+      # transaction_id are hashwise equal.
+      #
+      def eql?(o)
+        if TransactionProxy === o
+          o.transaction_id == @transaction_id
+        else
+          false
+        end
+      end
+      #
+      # Forwards everything to our Transaction and remembers
+      # returnvalue if necessary.
+      #
+      def method_missing(meth, *args) #:nodoc:
+        rval = @manager.call_instance_method(@transaction_id, meth, *args)
+        case meth
+        when :abort!
+          @state = :aborted
+        when :commit!
+          @state = rval
+        end
+        return rval
+      end
+    end
+    
+
+
+
+    #
+    # A transaction managed by the manager.
+    #
+    # A transaction can have the following states:
+    #
+    # * :active - When it is first created.
+    #   * This transaction can be commited or aborted.
+    #
+    # * :voting - When it has started the two-phase commit and the voting has begun.
+    #   * This transaction can be aborted.
+    #
+    # * :commited - After everyone has voted and voted either :unchanged or :commit.
+    #   * This transaction can not be changed.
+    #
+    # * :aborted - After someone has called abort! or voted :abort in a vote!
+    #   * This transaction can not be changed.
+    #
+    # Anyone that wants to join the transaction must implement the following methods:
+    #
+    # * abort!(transaction): Abort the provided transaction.
+    # * commit!(transaction): Commit the provided transaction.
+    # * prepare!(transaction): Prepare for commiting the provided transaction.
+    #
+    # abort! and commit! should not return any values, but can raise exceptions
+    # if required.
+    #
+    # prepare! must return either :abort, :commit or :unchanged, depending on what
+    # the member is prepared to do. :unchanged is only when the member has not changed
+    # state during the transaction, and means that it does not require any further
+    # notification on the progress of the transaction.
+    #
+    # A member that has returned :commit on the prepare! must store the transaction
+    # proxy in a persistent manner to be able to connect to the manager 
+    # and get a new copy of the transaction in case of communications failure.
+    #
+    # A member that reconnects to a crashed transaction manager should not abort! the 
+    # transaction if the transaction is still in :active state, since the transaction will 
+    # have been aborted on commit! anyway (since the manager will not be able to prepare! the 
+    # disconnected member after either the manager or member having crashed) if needed. 
+    # If the disconnect was just a temporary networking problem, the transaction will 
+    # continue as planned.
+    #
+    # A member that reconnects to a crashed transaction manager where the transaction
+    # is in :voting state should just wait around and see if it gets prepare! called.
+    # In case of temporary network failure the transaction will continue as planned, otherwise
+    # it will abort! automatically.
+    #
+    # A member that reconnects to a disconnected transaction manager where the transaction
+    # is in :commited state should just commit its state. Then it must notify the transaction
+    # using report_commited! so that the transaction can disappear gracefully.
+    #
+    # A member that reconnects to a disconnected transaction manager that either doesnt know
+    # of the transaction or returns an :aborted transaction may safely abort the state change
+    # and forget about the transaction.
+    #
+    class Transaction
+
+      include Archipelago::Current::Synchronized
+
+      attr_reader :state, :transaction_id, :proxy, :manager
+
+      #
+      # Create a transaction managed by the provided +manager+.
+      #
+      # Will have <i>:manager</i> as TransactionManager, and will timeout
+      # after <i>:timeout</i> seconds.
+      #
+      def initialize(options)
+        super()
+        #
+        # A hash where members are keys and their state the values.
+        #
+        @members = {}
+        @members.extend(Archipelago::Current::Synchronized)
+        #
+        # We are alive!
+        #
+        @state = :active
+        #
+        # We have a timeout!
+        #
+        @timeout = options[:timeout]
+        #
+        # We are unique!
+        # 
+        @transaction_id = "#{options[:manager].service_id}:#{Time.new.to_f}:#{self.object_id}:#{rand(1 << 32)}"
+        #
+        # We have a birth time!
+        #
+        @created_at = Time.now
+        #
+        # We have a manager!
+        #
+        self.manager = options[:manager]
+
+        store_us_for_future_reference!
+
+        start_timeout_thread
+      end
+
+      #
+      # Store this manager as ours and create a proxy that knows about it.
+      #
+      # Used by Archipelago::Tranny:Manager when restoring crashed
+      # Archipelago::Tranny:Transactions.
+      #
+      def manager=(manager)
+        #
+        # We have a manager!
+        #
+        @manager = DRbObject.new(manager)
+        #
+        # We have a proxy to send forth into the world!
+        #
+        @proxy = TransactionProxy.new(self)
+        nil
+      end
+
+      #
+      # Special dump call to NOT dump our manager or proxy,
+      # since DRbObjects dont take kindly to being restored
+      # in an environment where they are are known to be invalid.
+      #
+      def _dump(l)
+        return Marshal.dump([
+                             @members,
+                             @state,
+                             @timeout,
+                             @transaction_id,
+                             @created_at
+                            ])
+      end
+
+      def self._load(s)
+        members, state, timeout, transaction_id, created_at = Marshal.load(s)
+        rval = self.allocate
+        rval.instance_variable_set(:@members, members)
+        rval.instance_variable_set(:@state, state)
+        rval.instance_variable_set(:@timeout, timeout)
+        rval.instance_variable_set(:@transaction_id, transaction_id)
+        rval.instance_variable_set(:@created_at, created_at)
+        rval
+      end
+
+      #
+      # Starts the thread that will abort! us automatically
+      # after we have lived @timeout
+      #
+      def start_timeout_thread
+        Thread.new do
+          now = Time.now
+          die_at = @created_at + @timeout
+          if die_at > now
+            sleep(die_at - now)
+          end
+          abort!
+        end
+        nil
+      end
+
+      #
+      # What it sounds like.
+      #
+      def store_us_for_future_reference!
+        @manager.store_transaction!(self)
+        nil
+      end
+
+      #
+      # Remove ourselves, we are redundant
+      #
+      def remove_us_we_are_redundant!
+        @manager.remove_transaction!(self)
+        nil
+      end
+
+      #
+      # Used by members that failed during commit.
+      #
+      def report_commited!(member)
+        raise UnknownMemberException(member, self) unless @members.include?(member)
+        raise IllegalOperationException(:report_commited!, self) unless self.state == :commited
+
+        @members[member] = :commited
+        
+        remove_us_if_all_are_commited!
+        nil
+      end
+
+      #
+      # Abort the transaction, sending all participants the abort! message.
+      #
+      def abort!
+        synchronize do
+          raise IllegalOperationException.new(:abort!, self) if [:commited, :aborted].include?(self.state)
+          
+          #
+          # Set our state.
+          #
+          @state = :aborted
+
+          store_us_for_future_reference!
+
+          #
+          # Abort all members.
+          #
+          threads = []
+          @members.clone.each do |member, state|
+            raise RuntimeException.new("This is not supposed to be possible, but we are in abort! with member " +
+                                       "#{member.inspect} in state #{state.inspect}") if state == :commited
+            if state != :aborted
+              threads << Thread.new do 
+                begin
+                  member.abort!(self.proxy)
+                  @members.synchronize do
+                    @members[member] = :aborted
+                  end
+                rescue Exception => e
+                  @manager.log_error(e)
+                  #
+                  # We must not let the other members stop just
+                  # because one member failed. No more Mr Nice Guy!
+                  #
+                end
+              end
+            end
+          end
+          
+          #
+          # Wait for all members to finish.
+          #
+          threads.each do |thread|
+            thread.join
+          end
+
+          #
+          # No use having aborted transactions lying about.
+          #
+          # NB: This means that disconnected members that cant
+          # find their old transactions will have to presume they
+          # have been aborted.
+          #
+          remove_us_we_are_redundant!
+        end
+        nil
+      end
+
+      #
+      # Commits the transaction, returning the new state (:aborted | :commited)
+      #
+      def commit!
+        synchronize do
+          raise IllegalOperationException.new(:commit!, self) unless self.state == :active
+
+          #
+          # Vote for the outcome and act on it
+          #
+          case vote!
+          when :abort
+            abort!
+          when :commit
+            _commit!
+          when :unchanged
+            @state = :commited
+            remove_us_we_are_redundant!
+          end
+
+          return @state
+        end
+        nil
+      end
+
+      #
+      # Join a +member+ to this transaction.
+      #
+      # Will raise a JoinCountException if the given member has allready
+      # joined this transaction.
+      #
+      def join(member)
+        @members.synchronize do
+          raise IllegalOperationException.new(:join, self) unless self.state == :active
+          raise JoinCountException.new(member, self) if @members.include?(member)
+
+          @members[member] = :active
+        end
+        store_us_for_future_reference!
+        nil
+      end
+
+      private
+
+      #
+      # Commit the transaction, sending all participants the commit message.
+      #
+      # The transaction is commited by all members having commit! called.
+      #
+      def _commit!
+        #
+        # Set our state.
+        #
+        @state = :commited
+
+        store_us_for_future_reference!
+
+        #
+        # Commit all members.
+        #
+        threads = []
+        @members.clone.each do |member, state|
+          raise RuntimeException.new("This is not supposed to be possible, but we are in _commit with member " +
+                                     "#{member.inspect} in state #{state.inspect}") unless [:prepared, :commited].include?(state)
+          threads << Thread.new do 
+            begin
+              member.commit!(self.proxy)
+              @members.synchronize do
+                @members[member] = :commited
+              end
+            rescue Exception => e
+              @manager.log_error(e)
+              #
+              # We must not let the other members stop just
+              # because one member failed. No more Mr Nice Guy!
+              #
+            end
+          end
+        end
+
+        #
+        # Wait for all members to finish.
+        #
+        threads.each do |thread|
+          thread.join
+        end
+
+        remove_us_if_all_are_commited!
+      end
+
+      def remove_us_if_all_are_commited!
+        #
+        # Check to see if all members have been told about the decision.
+        #
+        all_have_commited = true
+        @members.each do |member, state|
+          all_have_commited = false unless state == :comitted
+        end
+
+        #
+        # If they have, remove ourselves from the manager.
+        #
+        remove_us_we_are_redundant! if all_have_commited
+      end
+
+      #
+      # Let the members of the transaction vote for its outcome.
+      #
+      # Members vote by having prepare! called.
+      #
+      # Valid returnvalues for the prepare! call are:
+      # :abort, if the member wants to abort the transaction
+      # :commit, if the member wants to commit the transaction
+      # :unchanged, if the member has not changed state during the transaction
+      #
+      def vote!
+        raise IllegalOperationException.new(:vote!, self) unless self.state == :active
+
+        @state = :voting
+
+        store_us_for_future_reference!
+
+        return_value = :commit
+
+        threads = []
+        @members.clone.each do |member, state|
+          raise RuntimeException.new("This is not supposed to be possible, but we are in vote! with member " +
+                                     "#{member.inspect} in state #{state.inspect}") unless state == :active
+          threads << Thread.new do 
+            this_result = nil
+            begin
+              this_result = member.prepare!(self.proxy)
+            rescue Exception => e
+              @manager.log_error(e)
+              this_result = :abort
+            end
+            @members.synchronize do
+              case this_result
+              when :abort
+                @members[member] = :aborted
+                return_value = :abort
+              when :unchanged
+                @members.delete(member)
+              else
+                @members[member] = :prepared
+              end
+            end
+          end
+        end
+
+        threads.each do |thread|
+          thread.join
+        end
+
+        if @members.empty?
+          return_value = :unchanged
+        end
+
+        return_value
+      end
+      
+    end
+  end
+
+end