roby 0.8.0 → 3.0.0

data/lib/roby/coordination/actions.rb

@@ -0,0 +1,106 @@
+module Roby
+    module Coordination
+        # Common functionality of coordination models that manipulate actions
+        # (ActionStateMachine, ActionScript)
+        class Actions < Base
+            extend Models::Actions
+
+            # @return [Coordination::Task] the currently active toplevel task
+            attr_reader :current_task
+
+            TaskInfo = Struct.new :required_tasks, :forwards
+
+            # Mapping from a Coordination::Models::Task object to the set of
+            # forwards that are defined for it
+            attr_reader :task_info
+
+            # Resolved captures
+            #
+            # This is currently only used by the {ActionStateMachine}
+            #
+            # @return [Hash<Models::Capture, Object>]
+            attr_reader :resolved_captures
+
+            def initialize(root_task, arguments = Hash.new)
+                super(root_task, arguments)
+                @task_info = resolve_task_info
+                @resolved_captures = Hash.new
+            end
+
+            def action_interface_model
+                model.action_interface
+            end
+
+            def task_info_for(task)
+                required_tasks  = model.required_tasks_for(task).map do |t, roles|
+                    [instance_for(t), roles]
+                end
+
+                forwards = Set.new
+                model.each_forward do |in_task, event, target|
+                    if in_task == task
+                        event  = instance_for(event)
+                        target = instance_for(target)
+                        forwards << [event, target]
+                    end
+                end
+                TaskInfo.new(required_tasks, forwards)
+            end
+
+            def resolve_task_info
+                result = Hash.new
+                model.each_task do |task|
+                    result[instance_for(task)] = task_info_for(task)
+                end
+                result
+            end
+
+            def dependency_options_for(toplevel, task, roles)
+                roles = roles.dup
+                if task.name
+                    roles << task.name
+                end
+                Hash[roles: roles,
+                    failure: :stop.or(:start.never),
+                    remove_when_done: true]
+            end
+
+            def start_task(toplevel, explicit_start: false)
+                task_info = self.task_info[toplevel]
+                tasks, forwards = task_info.required_tasks, task_info.forwards
+                variables = arguments.merge(resolved_captures)
+
+                instanciated_tasks = tasks.map do |task, roles|
+                    action_task = task.model.instanciate(root_task.plan, variables)
+                    root_task.depends_on(action_task, dependency_options_for(toplevel, task, roles))
+                    bind_coordination_task_to_instance(task, action_task, on_replace: :copy)
+                    task.model.setup_instanciated_task(self, action_task, variables)
+                    action_task
+                end
+
+                @current_task = toplevel
+                forwards.each do |source, target|
+                    source.resolve.on do |event|
+                        if target.resolve.task.running?
+                            target.resolve.emit(*event.context)
+                        end
+                    end
+                end
+
+                instanciated_tasks
+            end
+
+            def remove_current_task
+                current_task_child = root_task.find_child_from_role('current_task')
+                task_info[current_task].required_tasks.each do |task, roles|
+                    if state_name = task.name
+                        roles = [state_name, *roles]
+                    end
+                    if !roles.empty? && (child_task = root_task.find_child_from_role(roles.first))
+                        root_task.remove_roles(child_task, *roles)
+                    end
+                end
+            end
+        end
+    end
+end

data/lib/roby/coordination/base.rb

@@ -0,0 +1,145 @@
+module Roby
+    module Coordination
+        # Context for all the execution objects that can be attached to the
+        # action interface and/or tasks, such as state machines and scripts
+        class Base
+            extend Models::Base
+            
+            # The parent coordination object
+            #
+            # @return [nil,Base]
+            attr_reader :parent
+
+            # The task on which this execution context is being executed. It
+            # must fullfill model.task
+            # @return [Model<Roby::Task>]
+            def root_task
+                instance_for(model.root).task
+            end
+
+            # The plan this coordination object is part of
+            def plan
+                root_task.plan
+            end
+
+            # The set of arguments given to this execution context
+            # @return [Hash]
+            attr_reader :arguments
+
+            # A mapping from the model-level description of the context to the
+            # instance-level description
+            #
+            # @see instanciate
+            attr_reader :instances
+
+            # The execution context model
+            # @return [Model<Base>] a subclass of Base
+            def model
+                self.class
+            end
+
+            # Create a new coordination instance. The model is represented by
+            # this object's class
+            #
+            # @param [Roby::Task] root_task the task instance that should be
+            #   bound to {Models::Base#root}
+            # @param [Hash] arguments parametrization of this coordination
+            #   object. The list of known arguments can be accessed with
+            #   model.arguments (defined by {Models::Arguments}.
+            # @param [Hash] options
+            # @option options [:drop,:copy] :on_replace (:drop) defines what
+            #   should be done if the root task gets replaced. :drop means that
+            #   the state machine should not be passed to the new task. :copy
+            #   means that it should. Note that it only affects the root task.
+            #   All other tasks that are referred to inside the coordination
+            #   model are tracked for replacements.
+            # @option options [nil,Base] :parent (nil) the parent coordination
+            #   model. This is used so that the coordination tasks can be shared
+            #   across instances
+            def initialize(root_task = nil, arguments = Hash.new, options = Hash.new)
+                options = Kernel.validate_options options, on_replace: :drop, parent: nil
+
+                @arguments = model.validate_arguments(arguments)
+                @parent = options[:parent]
+                @instances = Hash.new
+                if root_task
+                    bind_coordination_task_to_instance(
+                        instance_for(model.root),
+                        root_task,
+                        on_replace: options[:on_replace])
+                    root_task.add_coordination_object(self)
+
+                    attach_fault_response_tables_to(root_task)
+                    
+                    if options[:on_replace] == :copy
+                        root_task.as_service.on_replacement do |old_task, new_task|
+                            old_task.remove_coordination_object(self)
+                            new_task.add_coordination_object(self)
+                            attach_fault_response_tables_to(new_task)
+                        end
+                    end
+                end
+            end
+
+            def attach_fault_response_tables_to(task)
+                model.each_used_fault_response_table do |table, arguments|
+                    arguments = arguments.map_value do |key, val|
+                        if val.kind_of?(Models::Variable)
+                            self.arguments[val.name]
+                        else val
+                        end
+                    end
+                    root_task.use_fault_response_table(table, arguments)
+                end
+            end
+
+            # Binds a task instance to the coordination task
+            #
+            # This method binds a task instance to the coordination task it
+            # represents, and optionally installs the handlers necessary to
+            # track replacement
+            #
+            # @param [Coordination::Task] coordination_task the coordination task
+            # @param [Roby::Task] instance the task
+            # @option options [Symbol] :on_replace (:drop) what should be done
+            #   if the task instance is replaced by another task. If :drop, the
+            #   coordination task will be reset to nil. If :copy, it will track
+            #   the new task
+            # @return [void]
+            def bind_coordination_task_to_instance(coordination_task, instance, options = Hash.new)
+                options = Kernel.validate_options options, on_replace: :drop
+
+                coordination_task.bind(instance)
+                if options[:on_replace] == :copy
+                    instance.as_service.on_replacement do |old_task, new_task|
+                        coordination_task.bind(new_task)
+                    end
+                end
+            end
+
+            # Returns the instance-level coordination task that is used to
+            # represent a model-level coordination task
+            #
+            # Coordination models are built using instances of
+            # {Coordination::Models::Task} (or its subclasses). When they get
+            # instanciated into actual coordination objects, these are
+            # uniquely associated with instances of {Coordination::Task} (or its
+            # subclasses).
+            #
+            # This method can be used to retrieve the unique object associated
+            # with a given model-level coordination task
+            #
+            # @param [Coordination::Models::Task] object the model-level coordination task
+            # @return [Coordination::Task] object the instance-level coordination task
+            def instance_for(object)
+                if !(ins = instances[object])
+                    if !parent || !(ins = parent.instances[object])
+                        ins = instances[object] = object.new(self)
+                    end
+                end
+                ins
+            end
+        end
+    end
+end
+

data/lib/roby/coordination/calculus.rb

@@ -0,0 +1,40 @@
+module Roby
+    module Tools
+        module Calculus
+            module Build
+                def self.unary_op(name)
+                    define_method(name) do
+                        Unary.new(name, self)
+                    end
+                end
+
+                def self.binary_op(name)
+                    define_method(name) do |arg|
+                        Binary.new(name, self, arg)
+                    end
+                end
+
+                unary_op :-@
+                unary_op :+@
+                binary_op :+
+                binary_op :-
+                binary_op :*
+                binary_op :/
+                binary_op :**
+            end
+            Unary  = Struct.new :op, :val do
+                def evaluate(variables)
+                    val.evaluate(variables).send(op)
+                end
+                include Build
+            end
+            Binary = Struct.new :op, :left, :right do
+                def evaluate(variables)
+                    left.evaluate(variables).send(op, right.evaluate(variables))
+                end
+                include Build
+            end
+        end
+    end
+end
+

data/lib/roby/coordination/child.rb

@@ -0,0 +1,28 @@
+module Roby
+    module Coordination
+            # Representation of the context's root task
+            class Child < TaskBase
+                # @return [Coordination::Task] this child's parent
+                attr_reader :parent
+
+                def root_task
+                    parent
+                end
+
+                def initialize(execution_context, model)
+                    super
+                    @parent = execution_context.instance_for(model.parent)
+                end
+
+                def resolve
+                    if result = parent.resolve.find_child_from_role(model.role)
+                        result
+                    else raise ResolvingUnboundObject, "#{parent.resolve}, resolved from #{parent} has not child named #{model.role}"
+                    end
+                end
+
+                def to_s; "#{parent}.#{model.role}_child[#{model.model}]" end
+            end
+    end
+end
+

data/lib/roby/coordination/event.rb

@@ -0,0 +1,29 @@
+module Roby
+    module Coordination
+            # Representation of the context's root task
+            class Event
+                # @return [Base] the underlying execution context
+                attr_reader :execution_context
+                # @return [Coordination::Task] the task this event is part
+                #   of
+                attr_reader :task
+                # @return [Coordination::Event]
+                attr_reader :model
+
+                def initialize(execution_context, model)
+                    @execution_context = execution_context
+                    @model = model
+                    @task  = execution_context.instance_for(model.task)
+                end
+
+                def symbol; model.symbol end
+
+                def resolve
+                    task.resolve.event(model.symbol)
+                end
+
+                def to_s; "#{task}.#{symbol}_event" end
+            end
+    end
+end
+

data/lib/roby/coordination/fault_handler.rb

@@ -0,0 +1,25 @@
+module Roby
+    module Coordination
+        class FaultHandler < ActionScript
+            extend Models::FaultHandler
+
+            def step
+                super
+                if finished?
+                    if model.carry_on?
+                        response_task = self.root_task
+                        plan = response_task.plan
+                        response_task.each_parent_object(Roby::TaskStructure::ErrorHandling) do |repaired_task|
+                            plan.replan(repaired_task)
+                        end
+                        response_task.success_event.emit
+                    end
+                end
+            end
+
+            def to_s
+                "#{self.class}/#{root_task}"
+            end
+        end
+    end
+end

data/lib/roby/coordination/fault_handling_task.rb

@@ -0,0 +1,13 @@
+module Roby
+    module Coordination
+        # Representation of a fault response from a {FaultResponseTable}
+        class FaultHandlingTask < Roby::Task
+            terminates
+
+            # @return [FaultHandler] the fault handler that this task represents
+            attr_accessor :fault_handler
+        end
+    end
+end
+
+

data/lib/roby/coordination/fault_response_table.rb

@@ -0,0 +1,110 @@
+module Roby
+    module Coordination
+        # A way to organize response to faults (a.k.a. Roby exceptions)
+        #
+        # Fault response tables are defined as subclasses of this class, e.g.
+        #
+        # @example
+        #   class MyTable < FaultResponseTable
+        #     on_fault with_origin(TaskModel.power_off_event) do
+        #       # Fault response description
+        #     end
+        #   end
+        #
+        # The fault response description is [an action
+        # script]({Coordination::ActionScript}). It is represented by a
+        # {FaultHandlingTask} that is added when a fault response triggers.
+        #
+        # When a {#on_fault} declaration matches an exception, the table will
+        # create a {FaultHandlingTask} task and attach it to a task in the plan.
+        # The task it attaches it to depends on statements that extend the
+        # action script:
+        #
+        #  * locate_on_missions: the fault response will be assigned to the
+        #    downmost missions which are affected by the fault.
+        #  * locate_on_actions:  the fault response will be assigned to the
+        #    downmost actions which are affected by the fault. This is the
+        #    default.
+        #  * locate_on_origins: the fault response will be assigned to the fault
+        #    origin
+        #
+        # The task on which the fault response is attached is stopped. The
+        # exception that caused the response is inhibited while the response is
+        # running.
+        #
+        # By default, once the fault response is finished, the plan will resume
+        # normal exception processing. I.e., it is the fault response's
+        # responsibility to fix the exception(s) in the plan. This default can
+        # be changed by adding the 'restart' statement in the action script. In
+        # this case, the mission or task that was assigned to the fault handler
+        # will be restarted once the fault handler script terminates. It can
+        # optionally be given a number of allowed restarts (to avoid infinite
+        # loops) as well as a timeout (to reset the counter if the fault did not
+        # occur for a certain length of time)
+        #
+        # And can then be attached to plans within an action interface:
+        #  
+        # @example enable a fault response table globally
+        #   use_fault_response_table MyTable
+        #
+        # @example enable this fault response table whenever a task matching this matcher
+        #   use_fault_response_table MyTable, when: MyTaskModel.mission
+        # 
+        # @example enable this fault response table when this action is running
+        #   use_fault_response_table MyTable, when: an_action
+        #
+        # @example dynamically enable/disable tables programatically
+        #   Roby.plan.use_fault_response_table MyTable
+        #   Roby.plan.remove_fault_response_table MyTable
+        #
+        class FaultResponseTable < Roby::Actions::Interface
+            extend Models::FaultResponseTable
+
+            # @return [{Symbol=>Object}] assigned table arguments
+            attr_reader :arguments
+
+            def initialize(plan, arguments = Hash.new)
+                # Argument massaging must be done before we call super(), as
+                # super() will attach the table on the plan
+                @arguments = model.validate_arguments(arguments)
+                super(plan)
+            end
+
+            # Hook called when this table is attached to a given plan
+            #
+            # This is a hook, so one can inject code here by defining a
+            # attach_to method on a module and prepending the module on the
+            # FaultResponseTable class. Do not forget to call super
+            # in the hook method.
+            #
+            # @param [Plan] plan
+            # @return [void]
+            def attach_to(plan)
+            end
+
+            # Returns the handlers that are defined for a particular exception
+            #
+            # @param [ExecutionException] exception the exception that should be
+            #   matched
+            # @return [Array<Models::FaultHandler>]
+            def find_all_matching_handlers(exception)
+                model.find_all_matching_handlers(exception)
+            end
+
+            # Called when this table has been removed from the plan it was
+            # attached to
+            #
+            # It cannot be reused afterwards
+            #
+            # It calls super if it is defined, so it is possible to use it as a
+            # hook by defining a module that defines removed! and prepend it in
+            # the FaultResponseTable class. Don't forget to call super in the
+            # hook
+            #.
+            # @return [void]
+            def removed!
+            end
+        end
+    end
+end
+