roby 0.8.0 → 3.0.0

data/lib/roby/actions/models/interface.rb

@@ -0,0 +1,22 @@
+module Roby
+    module Actions
+        module Models
+            module Interface
+                include Models::InterfaceBase
+                include MetaRuby::ModelAsClass
+
+                # @api private
+                #
+                # Internal handler for MetaRuby's inherited-attribute functionality.
+                # It updates an action from a parent model to match this model.
+                #
+                # In particular, it updates coordination models to point to actions
+                # of this 
+                def promote_registered_action(name, action)
+                    actions[name] ||= action.rebind(self)
+                end
+            end
+        end
+    end
+end
+

data/lib/roby/actions/models/interface_base.rb

@@ -0,0 +1,294 @@
+module Roby
+    module Actions
+        module Models
+        module InterfaceBase
+            # IMPORTANT: ModelAsClass / ModelAsModule must NOT be included here.
+            # This interface model is used by both Interface (which is a
+            # ModelAsClass) and Library (which is a ModelAsModule)
+            extend MetaRuby::Attributes
+
+            # @api private
+            #
+            # Internal handler for MetaRuby's inherited-attribute functionality.
+            # This method does nothing, it's here so that the registered_action
+            # attribute gets promotion enabled. It's overloaded in Interface to
+            # actually rebind the action to the interface
+            def promote_registered_action(name, action)
+                action
+            end
+
+            # The set of actions defined on this interface
+            #
+            # @return [Hash<String,Models::Action>]
+            # @key_name action_name
+            inherited_attribute(:registered_action, :actions, map: true) { Hash.new }
+
+            # The set of fault response tables added to this action interface
+            # @return [Array<Model<FaultResponseTable>>]
+            inherited_attribute(:fault_response_table, :fault_response_tables) { Array.new }
+
+            # Exception raised when an action is defined with the wrong count of
+            # argument (zero if no arguments are specified and one if arguments
+            # are specified)
+            class ArgumentCountMismatch < ScriptError; end
+
+            # Adds all actions defined in another action interface or in an
+            # action library in this interface
+            #
+            # @param [Module,Interface]
+            # @return [void]
+            def use_library(library)
+                if library <= Actions::Interface
+                    library.each_registered_action do |name, action|
+                        actions[name] ||= action
+                    end
+                    library.each_fault_response_table do |table|
+                        use_fault_response_table table
+                    end
+                else
+                    include library
+                end
+            end
+
+            # Enumerates the actions registered on this interface
+            #
+            # @yieldparam [Models::Action] action
+            def each_action
+                return enum_for(:each_action) if !block_given?
+                each_registered_action do |_, description|
+                    yield(description)
+                end
+            end
+
+            # Clears everything stored on this model
+            def clear_model
+                super
+                actions.clear
+            end
+
+            # Create a new action description that is going to be used to
+            # describe the next method. Note that only methods that have a
+            # description are exported as actions
+            #
+            # @return Action
+            def describe(doc = nil)
+                if @current_description
+                    Actions::Interface.warn "the last #describe call was not followed by an action definition. Did you forget to add a method to your action interface ?"
+                end
+                @current_description = Models::Action.new(doc)
+            end
+
+            # Registers a new action on this model
+            #
+            # If no specific return type has been specified, one is created
+            # automatically and registered as a constant on this action
+            # interface. For instance, the start_all_devices action would create
+            # a simple StartAllDevices task model.
+            def register_action(name, action_model)
+                name = name.to_s
+                create_default_action_return_type(name, action_model)
+                action_model.name = name
+                actions[action_model.name] = action_model
+            end
+
+            # @api private
+            #
+            # Create and register the default task model for a given action
+            # model if needed (i.e. if the action model does not have an
+            # explicit return type yet)
+            def create_default_action_return_type(name, action_model)
+                return if action_model.returned_type != Roby::Task
+
+                task_model_name = name.camelcase(:upper)
+                if const_defined_here?(task_model_name)
+                    action_model.returns(const_get(task_model_name))
+                else
+                    task_model = Roby::Task.new_submodel do
+                        terminates
+                    end
+                    const_set task_model_name, task_model
+                    task_model.permanent_model = self.permanent_model?
+                    action_model.returns(task_model)
+                end
+            end
+
+
+            # Hook used to export methods for which there is a description
+            def method_added(method_name)
+                super
+                if @current_description
+                    name = method_name.to_s
+                    description, @current_description = @current_description, nil
+                    description = MethodAction.new(self, description)
+
+                    if existing = find_action_by_name(name)
+                        if description.returned_type == Roby::Task
+                            description.returns(existing.returned_type)
+                        end
+                        description.overloads(existing)
+                    end
+
+                    expected_argument_count =
+                        if description.arguments.empty? then 0
+                        else 1
+                        end
+                    begin
+                        check_arity(instance_method(name), expected_argument_count)
+                    rescue ArgumentError => e
+                        if expected_argument_count == 0
+                            raise ArgumentCountMismatch, "action #{name} has been declared to have no arguments, the #{name} method must be callable without any arguments"
+                        else
+                            raise ArgumentCountMismatch, "action #{name} has been declared to have arguments, the #{name} method must be callable with a single Hash argument"
+                        end
+                    end
+                    register_action(name, description)
+                end
+            end
+
+            # Returns the action description for the given action name, or nil
+            # if there are none with that name
+            #
+            # @param [String] name
+            # @return [Models::Action,nil]
+            def find_action_by_name(name)
+                find_registered_action(name.to_s)
+            end
+
+            # Returns all the action description for the actions that can
+            # produce such a task
+            #
+            # @param [Roby::Task,Roby::TaskService] type
+            # @return [Array<Models::Action>]
+            def find_all_actions_by_type(type)
+                result = []
+                each_action do |description|
+                    if description.returned_type.fullfills?(type)
+                        result << description
+                    end
+                end
+                result
+            end
+
+            # @api private
+            #
+            # Verifies that #describe was called to describe an action that is
+            # now being defined, and returns it
+            #
+            # The current description is nil after this call
+            #
+            # @raise [ArgumentError] if describe was not called
+            def require_current_description
+                action_model, @current_description = @current_description, nil
+                if action_model
+                    action_model
+                else
+                    raise ArgumentError, "you must describe the action with #describe before calling #action_coordination"
+                end
+            end
+
+            def create_and_register_coordination_action(name, coordination_class, action_model: require_current_description, &block)
+                name = name.to_s
+                create_default_action_return_type(name, action_model)
+                action_model, coordination_model =
+                    create_coordination_action(action_model, coordination_class, &block)
+                register_action(name, action_model)
+                coordination_model.name = name
+
+                define_method(name) do |**arguments|
+                    action_model.instanciate(plan, **arguments)
+                end
+
+                return action_model, coordination_model
+            end
+
+            def create_coordination_model(action_model, coordination_class, &block)
+                root_m    = action_model.returned_type
+                coordination_model = coordination_class.
+                    new_submodel(action_interface: self, root: root_m)
+
+                action_model.arguments.each do |arg|
+                    if !arg.required
+                        coordination_model.argument arg.name, default: arg.default
+                    else
+                        coordination_model.argument arg.name
+                    end
+                end
+                coordination_model.parse(&block)
+                coordination_model
+            end
+
+            # Helper method for {#action_state_machine} and {#action_script}
+            def create_coordination_action(action_model, coordination_class, &block)
+                coordination_model = create_coordination_model(action_model, coordination_class, &block)
+                action_model = CoordinationAction.new(coordination_model, action_model)
+                return action_model, coordination_model
+            end
+
+            # Defines an action from an
+            # {Coordination::Models::ActionStateMachine}
+            #
+            # @param [String] name the name of the new action
+            # @yield the action state machine definition
+            # @return [Action,Coordination::Models::ActionStateMachine]
+            #
+            # The action state machine model can later be retrieved using
+            # {Action#coordination_model}
+            #
+            # @example (see Coordination::Models::ActionStateMachine)
+            def action_state_machine(name, &block)
+                action_model = require_current_description
+
+                # Define user-possible starting states, this will override the default starting state
+                if action_model.has_arg?("start_state")
+                    raise ArgumentError, "A argument \"start_state\" has defined for the statemachine, but this keyword is reserved"
+                end
+                action_model.optional_arg("start_state", "name of the state in which the state machine should start", nil)
+                create_and_register_coordination_action(name, Coordination::ActionStateMachine, action_model: action_model, &block)
+            end
+
+            # @deprecated use {#action_state_machine} instead
+            def state_machine(name, &block)
+                action_state_machine(name, &block)
+            end
+
+            # Defines an action from an
+            # {Coordination::Models::ActionScript}
+            #
+            # @param [String] name the name of the new action
+            # @yield the action script definition
+            # @return [Action,Coordination::Models::ActionScript]
+            #
+            # The action script model can later be retrieved using
+            # {Action#coordination_model}
+            def action_script(name, options = Hash.new, &block)
+                create_and_register_coordination_action(name, Coordination::ActionScript, &block)
+            end
+
+            def respond_to_missing?(m, include_private)
+                find_action_by_name(m.to_s) || super
+            end
+
+            # Returns an action description if 'm' is the name of a known action
+            #
+            # @return [Action]
+            def method_missing(m, *args)
+                if model = find_action_by_name(m.to_s)
+                    if args.size > 1
+                        raise ArgumentError, "expected zero or one argument, got #{args.size}"
+                    end
+                    return model.new(*args)
+                end
+                super
+            end
+
+            # Declare that this fault response table should be used on all plans
+            # that are going to use this action interface
+            def use_fault_response_table(table_model, arguments = Hash.new)
+                table_model.validate_arguments(arguments)
+                fault_response_tables << [table_model, arguments]
+            end
+        end
+        end
+    end
+end
+

data/lib/roby/actions/models/library.rb

@@ -0,0 +1,12 @@
+module Roby
+    module Actions
+        module Models
+            # Metamodel for action libraries
+            class Library < Module
+                include Models::InterfaceBase
+                include MetaRuby::ModelAsModule
+                include MetaRuby::Registration
+            end
+        end
+    end
+end

data/lib/roby/actions/models/method_action.rb

@@ -0,0 +1,90 @@
+module Roby
+    module Actions
+        module Models
+            # Action defined by a method on an {Interface}
+            class MethodAction < Action
+                # The action interface on which this action is defined
+                attr_accessor :action_interface_model
+
+                def initialize(action_interface_model, doc = nil)
+                    super(doc)
+                    @action_interface_model = action_interface_model
+                end
+
+                def to_s
+                    "#{super} of #{action_interface_model}"
+                end
+            
+                def ==(other)
+                    other.kind_of?(self.class) &&
+                        other.action_interface_model == action_interface_model &&
+                        other.name == name
+                end
+
+                # Instanciate this action on the given plan
+                def instanciate(plan, arguments = Hash.new)
+                    action_interface = action_interface_model.new(plan)
+
+                    if self.arguments.empty?
+                        if !arguments.empty?
+                            raise ArgumentError, "#{name} expects no arguments, but #{arguments.size} are given"
+                        end
+                        result = action_interface.send(name).as_plan
+                    else
+                        default_arguments = self.arguments.inject(Hash.new) do |h, arg|
+                            h[arg.name] = arg.default
+                            h
+                        end
+                        arguments = Kernel.validate_options arguments, default_arguments
+                        self.arguments.each do |arg|
+                            if arg.required && !arguments.has_key?(arg.name.to_sym)
+                                raise ArgumentError, "required argument #{arg.name} not given to #{name}"
+                            end
+                        end
+                        result = action_interface.send(name, arguments).as_plan
+                    end
+                    # Make the planning task inherit the model/argument flags
+                    if planning_task = result.planning_task
+                        if planning_task.respond_to?(:action_model=)
+                            planning_task.action_model ||= self
+                        end
+                        if planning_task.respond_to?(:action_arguments=)
+                            result.planning_task.action_arguments ||= arguments
+                        end
+                    end
+                    result
+                end
+
+                # Create a new action model that is bound to a different interface model
+                #
+                # @param [Models::Interface] action_interface_model the new model
+                # @param [Boolean] force the rebind will happen only if the new
+                #   interface model is a submodel of the current one. If force is
+                #   true, it will be done regardless.
+                # @return [Action] the rebound action model
+                def rebind(action_interface_model)
+                    rebound = dup
+                    if action_interface_model <= self.action_interface_model
+                        rebound.action_interface_model = action_interface_model
+                    end
+                    rebound
+                end
+
+                # Returns the plan pattern that will deploy this action on the plan
+                def plan_pattern(arguments = Hash.new)
+                    job_id, arguments = Kernel.filter_options arguments, :job_id
+
+                    planner = Roby::Actions::Task.new(
+                        Hash[action_model: self,
+                             action_arguments: arguments].merge(job_id))
+                    planner.planning_result_task
+                end
+
+                def to_s
+                    "#{action_interface_model.name}.#{name}"
+                end
+            end
+        end
+    end
+end
+

data/lib/roby/actions/task.rb

@@ -0,0 +1,114 @@
+module Roby
+    module Actions
+        # A task that calls an action interface to generate a plan
+        class Task < Roby::Task
+            terminates
+
+            provides Roby::Interface::Job
+
+            # Once the task has been started, this is the transaction object that
+            # is being used / has been used to generate before committing in the
+            # plan
+            # @return [Transaction]
+            attr_reader :transaction
+
+            # The action itself
+            # @return [Models::Action]
+            argument :action_model
+            # The arguments for the action method
+            # @return [Hash]
+            argument :action_arguments, default: Hash.new
+
+            # The model of the roby task that is going to represent the action
+            # in the plan
+            # @return [Model<Roby::Task>] 
+            def planned_model
+                action_model.returned_task_type
+            end
+
+            # The action interface model used by this planner
+            # @return [Model<Interface>]
+            def action_interface_model
+                action_model.action_interface_model
+            end
+                
+            def job_name
+                formatted_arguments = (action_arguments || Hash.new).map do |k, v|
+                    "#{k} => #{v}"
+                end.join(", ")
+                "#{action_model}(#{formatted_arguments})"
+            end
+
+            def to_s
+                if action_model
+                    "#{super}[#{action_interface_model}:#{action_model}](#{action_arguments}) -> #{action_model.returned_type}"
+                else "#{super}"
+                end
+            end
+
+            def planning_result_task
+                if success? || result
+                    result
+                elsif task = planned_tasks.find { true }
+                    task
+                elsif pending?
+                    task = planned_model.new
+                    task.planned_by self
+                    task.abstract = true
+                    task
+                end
+            end
+
+            # The transaction in which we build the new plan. It gets committed on
+            # success.
+            attr_reader :transaction
+            # The planner result. It is either an exception or a task object
+            attr_reader :result
+
+            # Starts planning
+            event :start do |context|
+                if owners.size > 1
+                    @transaction = Distributed::Transaction.new(plan)
+                    owners.each do |peer|
+                        transaction.add_owner peer
+                    end
+                else
+                    @transaction = Transaction.new(plan)
+                end
+                start_event.emit
+            end
+
+            poll do
+                result_task = action_model.instanciate(transaction, action_arguments)
+
+                # Don't replace the planning task with ourselves if the
+                # transaction specifies another planning task
+                if new_planning_task = result_task.planning_task
+                    if !new_planning_task.arguments.set?(:job_id)
+                        new_planning_task.job_id = job_id
+                    end
+                else
+                    result_task.planned_by transaction[self]
+                end
+
+                if placeholder = planning_result_task
+                    placeholder = transaction[placeholder]
+                    transaction.replace(placeholder, result_task)
+                    placeholder.remove_planning_task transaction[self]
+                end
+
+                # If the transaction is distributed, and is not proposed to all
+                # owners, do it
+                transaction.propose
+                transaction.commit_transaction
+                @result = result_task
+                success_event.emit
+            end
+
+            on :failed do |event|
+                transaction.discard_transaction
+            end
+        end
+    end
+end
+