require 'roby'
require 'roby/distributed/distributed_object'
require 'roby/distributed/proxy'

module Roby
    module Distributed
	class << self
            # The block which is called when a new transaction has been proposed to us.
	    attr_accessor :transaction_handler

	    # Sets up the transaction handler. The given block will be called
	    # in a separate thread whenever a remote peer proposes a new
	    # transaction
	    def on_transaction(&block)
		Distributed.transaction_handler = block
	    end
	end

        # Raised when an operation needs the edition token, while the local
        # plan manager does not have it.
	class NotEditor < RuntimeError; end
        # Raised when a commit is attempted while the transaction is not ready,
        # i.e. the token should be passed once more in the edition ring.
	class NotReady < RuntimeError; end

        # An implementation of a transaction distributed over multiple plan
        # managers.  The transaction modification protocol is based on an
        # edition token, which is passed through all the transaction owners by
        # #edit and #release.
        #
        # Most operations on this distributed transaction must be done outside
        # the control thread, as they are blocking.
        #
        # See DistributedObject for a list of operations valid on distributed objects.
	class Transaction < Roby::Transaction
	    attr_reader :owners
	    attr_reader :token_lock, :token_lock_signal
	    include DistributedObject

            # Create a new distributed transaction based on the given plan. The
            # transaction sole owner is the local plan manager, which is also
            # the owner of the edition token.
	    def initialize(plan, options = {})
		@owners  = [Distributed]
		@editor  = true

		@token_lock = Mutex.new
		@token_lock_signal = ConditionVariable.new

		super
	    end

	    def do_wrap(base_object, create) # :nodoc:
		# It is allowed to add objects in a transaction only if
		#   * the object is not distribuable. It means that we are
		#     annotating *locally* remote tasks (like it is done for
		#     ConnectionTask for instance).
		#   * the object is owned by the transaction owners
		if create && (base_object.distribute? && !(base_object.owners - owners).empty?)
		    raise OwnershipError, "plan owners #{owners} do not own #{base_object}: #{base_object.owners}"
		end

		temporarily_subscribed = !base_object.updated?
		if temporarily_subscribed
		    peer = base_object.owners.first
		    base_object = peer.subscribe(base_object)
		end

		if object = super
		    object.extend DistributedObject
		    if !Distributed.updating?(self) && object.root_object? && base_object.distribute?
			# The new proxy has been sent to remote hosts since it
			# has been discovered in the transaction. Nonetheless,
			# we don't want to return from #wrap until we know its
			# sibling. Add a synchro point to wait for that
		        updated_peers.each do |peer|
		            peer.synchro_point
		        end
		    end
		end

		object

	    ensure
		if temporarily_subscribed
		    peer.unsubscribe(base_object)
		end
	    end

	    def copy_object_relations(object, proxy) # :nodoc:
		# If the transaction is being updated, it means that we are
		# discovering the new transaction. In that case, no need to
		# discover the plan relations since our peer will send us all
		# transaction relations
		unless Distributed.updating?(self)
		    super
		end
	    end

	    # Checks that +peer+ can be removed from the list of owners
	    def prepare_remove_owner(peer)
		known_tasks.each do |t|
		    t = t.__getobj__ if t.respond_to?(:__getobj__)
		    if peer.owns?(t) && t.distribute?
			raise OwnershipError, "#{peer} still owns tasks in the transaction (#{t})"
		    end
		end
		nil
	    end

            # Announces the transaction on +peer+ or, if +peer+ is nil, to all
            # owners who don't know about it yet. This operation is
            # asynchronous, so the block, if given, will be called for each
            # remote peer which has processed the message.
            #
            # See Peer#transaction_propose
	    def propose(peer = nil, &block)
		if !self_owned?
		    raise OwnershipError, "cannot propose a transaction we don't own"
		end

		if peer
		    peer.transaction_propose(self, &block)
		else
		    (owners - remote_siblings.keys).each do |peer|
			if peer != Roby::Distributed
			    Distributed.debug "proposing #{self} to #{peer}"
			    propose(peer) do
				yield(peer)
			    end
			end
		    end
		end
	    end

	    def discover(objects) # :nodoc:
		if objects
		    events, tasks = partition_event_task(objects)
		    for object in (events || []) + (tasks || [])
			unless Distributed.updating?(object) || 
			    Distributed.owns?(object) || 
			    (object.owners - owners).empty?

			    raise OwnershipError, "#{object} is not owned by #{owners.to_a} (#{object.owners.to_a})"
			end
		    end
		    super(events) if events
		    super(tasks) if tasks
		else
		    super
		end
	    end

	    # call-seq:
	    #   commit_transaction => self
	    #
            # Commits the transaction. This method can only be called by the
            # first editor of the transaction, once all owners have requested
            # no additional modifications.
            #
            # Distributed commits are done in two steps, to make sure that all
            # owners agree to actually perform it. First, the
            # PeerServer#transaction_prepare_commit message is sent, which can
            # return either nil or an error object.
            #
            # If all peers return nil, the actual commit is performed by
            # sending the PeerServer#transaction_commit message. Otherwise, the
            # commit is abandonned by sending the
            # PeerServer#transaction_abandon_commit message to the transaction
            # owners.
	    def commit_transaction(synchro = true)
		if !self_owned?
		    raise OwnershipError, "cannot commit a transaction which is not owned locally. #{self} is owned by #{owners.to_a}"
		elsif synchro
		    if !editor?
			raise NotEditor, "not editor of this transaction"
		    elsif !first_editor?
			raise NotEditor, "transactions are committed by their first editor"
		    elsif edition_reloop
			raise NotReady, "transaction still needs editing"
		    end
		end

		if synchro
		    result = call_owners(:transaction_prepare_commit, self)
		    error = result.find_all { |_, returned| returned }
		    if !error.empty?
			call_owners(:transaction_abandon_commit, self, error)
			return false
		    else
			call_owners(:transaction_commit, self)
			return true
		    end
		else
		    all_objects = known_tasks.dup
		    proxy_objects.each_key { |o| all_objects << o }
		    Distributed.update(self) do
			Distributed.update_all(all_objects) do
			    super()
			end
		    end
		end

		self
	    end

	    # Hook called when the transaction commit has been abandoned
	    # because a owner refused it. +reason+ is the value returned by
	    # this peer.
	    def abandoned_commit(error)
		Distributed.debug { "abandoned commit of #{self} because of #{error}" }
		super if defined? super 
	    end

	    # call-seq:
	    #	discard_transaction	    => self 
	    #
            # Discards the transaction. Unlike #commit_transaction, this can be
            # called by any of the owners.
	    def discard_transaction(synchro = true) # :nodoc:
		unless Distributed.owns?(self)
		    raise OwnershipError, "cannot discard a transaction which is not owned locally. #{self} is owned by #{owners}"
		end

		if synchro
		    call_siblings(:transaction_discard, self)
		else super()
		end
		self
	    end

            # True if we currently have the edition token
            attr_predicate :editor?
            # True if one of the editors request that the token is passed to
            # them once more. The transaction can be committed only when all
            # peers did not request that.
            #
            # See #release
	    attr_reader :edition_reloop

            # True if this plan manager is the first editor, i.e. the plan
            # manager whose responsibility is to manage the edition protocol.
	    def first_editor?
		owners.first == Distributed
	    end
            # Returns the peer which is after this plan manager in the edition
            # order.  The edition token will be sent to this peer by #release
	    def next_editor
		if owners.last == Distributed
		    return owners.first
		end

		owners.each_cons(2) do |first, second|
		    if first == Distributed
			return second
		    end
		end
	    end

	    def edit!(reloop)
		token_lock.synchronize do
		    @editor = true
		    @edition_reloop = reloop
		    token_lock_signal.broadcast
		end
	    end

            # Waits for the edition token. If a block is given, it is called
            # when the token is achieved, and releases the token when the
            # blocks returns.
	    def edit(reloop = false)
		if Thread.current[:control_mutex_locked]
		    raise "cannot call #edit with the control mutex taken !"
		end

		token_lock.synchronize do
		    if !editor? # not the current editor
			token_lock_signal.wait(token_lock)
		    end
		end

		if block_given?
		    begin
			yield
		    ensure
			release(reloop)
		    end
		end
	    end

            # Releases the edition token, giving it to the next owner. If
            # +give_back+ is true, the local plan manager announces that it
            # expects the token to be given back to it once more. The commit is
            # allowed only when all peers have released the edition token
            # without requesting it once more.
            #
            # It sends the #transaction_give_token to the peer returned by
            # #next_editor.
            #
            # Raised NotEditor if the local plan manager is not the current
            # transaction editor.
	    def release(give_back = false)
		token_lock.synchronize do
		    if !editor?
			raise NotEditor, "not editor"
		    else
			reloop = if first_editor?
				     give_back
				 else
				     edition_reloop || give_back
				 end

			return if owners.size == 1
			@editor = false
			next_editor.transaction_give_token(self, reloop)
			true
		    end
		end
	    end

            # Intermediate representation of a Roby::Distributed::Transaction
            # object, suitable for representing that transaction in the dRoby
            # protocol.
	    class DRoby < Roby::BasicObject::DRoby
		attr_reader :plan, :options
		def initialize(remote_siblings, owners, plan, options)
		    super(remote_siblings, owners)
		    @plan, @options = plan, options
		end

                # Returns the local representation of this transaction, or
                # raises InvalidRemoteOperation if none exists.
		def proxy(peer)
		    raise InvalidRemoteOperation, "the transaction #{self} does not exist on #{peer.connection_space.name}"
		end

                # Create a local representation for this transaction.
		def sibling(peer)
		    plan = peer.local_object(self.plan)
		    trsc = Roby::Distributed::Transaction.new(plan, peer.local_object(options))
		    update(peer, trsc)
		    trsc.instance_eval do
			@editor  = false
		    end
		    trsc
		end

                # Called when a new sibling has been created locally for a
                # distributed transaction present on +peer+. +trsc+ is the
                # local representation of this transaction.
                #
                # In practice, it announces the new transaction by calling the
                # block stored in Distributed.transaction_handler (if there is
                # one).
                #
                # See PeerServer#created_sibling
		def created_sibling(peer, trsc)
		    Thread.new do
			Thread.current.priority = 0
			begin
			    Distributed.transaction_handler[trsc] if Distributed.transaction_handler
			rescue 
			    Roby.warn "transaction handler for #{trsc} failed"
			    Roby.warn $!.full_message
			    trsc.invalidate("failed transaction handler")
			end
		    end
		end

		def to_s # :nodoc:
		    "#<dRoby:Trsc#{remote_siblings_to_s} owners=#{owners_to_s} plan=#{plan}>"
		end
	    end

            # Returns a representation of +self+ which can be used to reference
            # it in our communication with +dest+.
	    def droby_dump(dest) # :nodoc:
		if remote_siblings.has_key?(dest)
		    remote_id
		else
		    DRoby.new(remote_siblings.droby_dump(dest), owners.droby_dump(dest), 
			      plan.droby_dump(dest), 
			      options.droby_dump(dest))
		end
	    end
	end

	module Roby::Transaction::Proxy
	    def droby_dump(dest) # :nodoc:
		DRoby.new(remote_siblings.droby_dump(dest), owners.droby_dump(dest),
			 Distributed.format(@__getobj__, dest), Distributed.format(transaction, dest))
	    end

            # A representation of a distributed transaction proxy suitable for
            # communication with the remote plan managers.
	    class DRoby < Roby::BasicObject::DRoby
                # The DRoby version of the underlying object
		attr_reader :real_object
                # The DRoby representation of the transaction
                attr_reader :transaction
                # Create a new dRoby representation for a transaction proxy.
                # The proxy currently has the given set of remote siblings and
                # owners, is a view on the given real object and is stored in
                # the given transaction. All objects must already be formatted
                # for marshalling using Distributed.format.
		def initialize(remote_siblings, owners, real_object, transaction)
		    super(remote_siblings, owners)
		    @real_object, @transaction = real_object, transaction 
		end

                # Returns the local object matching this dRoby-formatted
                # representation of a remote transaction proxy present on
                # +peer+.
		def proxy(peer)
		    local_real = peer.local_object(real_object)
		    local_object = nil
		    local_transaction = peer.local_object(transaction)
		    Distributed.update(local_transaction) do
			local_object = local_transaction[local_real]
		    end
		    local_object
		end

		def to_s # :nodoc:
                    "#<dRoby:mTrscProxy#{remote_siblings} transaction=#{transaction} real_object=#{real_object}>"
                end
	    end
	end

	class Roby::Transactions::TaskEventGenerator
            # A task event generator has no remote sibling. It is always
            # referenced through its own task.
	    def has_sibling?(peer); false end
            # Create an intermediate object which represent this task event
            # generator in our communication with +dest+
	    def droby_dump(dest)
		Roby::TaskEventGenerator::DRoby.new(controlable?, happened?, Distributed.format(task, dest), symbol)
	    end
	end

	class PeerServer
            # Message received when the 'prepare' stage of the transaction
            # commit is requested.
	    def transaction_prepare_commit(trsc)
		trsc = peer.local_object(trsc)
		peer.connection_space.transaction_prepare_commit(trsc)
		trsc.freezed!
		nil
	    end
            # Message received when a transaction commit is requested.
	    def transaction_commit(trsc)
		trsc = peer.local_object(trsc)
		peer.connection_space.transaction_commit(trsc)
		nil
	    end
            # Message received when a transaction commit is to be abandonned.
	    def transaction_abandon_commit(trsc, error)
		trsc = peer.local_object(trsc)
		peer.connection_space.transaction_abandon_commit(trsc, error)
		nil
	    end
            # Message received when a transaction discard is requested.
	    def transaction_discard(trsc)
		trsc = peer.local_object(trsc)
		peer.connection_space.transaction_discard(trsc)
		nil
	    end
            # Message received when the transaction edition token is given to
            # this plan manager.
	    def transaction_give_token(trsc, needs_edition)
		trsc = peer.local_object(trsc)
		trsc.edit!(needs_edition)
		nil
	    end
	end

	class Peer
            # Send the information related to the given transaction in the
            # remote plan manager.
	    def transaction_propose(trsc)
		synchro_point
		create_sibling(trsc)
		nil
	    end

            # Give the edition token on +trsc+ to the given peer.
            # +needs_edition+ is a flag which, if true, requests that the token
            # is given back at least once to the local plan manager.
            #
            # Do not use this directly, it is part of the multi-robot
            # communication protocol. Use the edition-related methods on
            # Distributed::Transaction instead.
	    def transaction_give_token(trsc, needs_edition)
		call(:transaction_give_token, trsc, needs_edition)
	    end
	end
    end
end