roby 0.8.0 → 3.0.0

data/lib/roby/task_structure/error_handling.rb

@@ -0,0 +1,118 @@
+module Roby::TaskStructure
+    class Roby::TaskEventGenerator
+        # Mark this event as being handled by the task +task+
+        def handle_with(repairing_task, remove_when_done: true)
+            if repairing_task.respond_to?(:as_plan)
+                repairing_task = repairing_task.as_plan
+            end
+
+            if !task.child_object?(repairing_task, ErrorHandling)
+                task.add_error_handler repairing_task, Set.new
+            end
+
+            if remove_when_done
+                repairing_task.stop_event.on do |event|
+                    repairing_task = event.task
+                    if task.plan && task.child_object?(repairing_task, ErrorHandling)
+                        task.remove_error_handler(repairing_task)
+                    end
+                end
+            end
+
+            task[repairing_task, ErrorHandling] << Roby::Queries::ExecutionExceptionMatcher.new.with_origin(task.model.find_event(symbol))
+            repairing_task
+        end
+    end
+
+    relation :ErrorHandling, child_name: :error_handler, strong: true, scheduling: true
+
+    module ErrorHandling::Extension
+        def repaired_tasks
+            each_parent_object(ErrorHandling).to_a
+        end
+
+        def failed_task
+            # For backward compatibility only. One should use #repaired_tasks
+            repaired_tasks.first
+        end
+
+        # Tests if this task can be used to repair an exception
+        #
+        # It is different from {#repairs_error?} as the latter tests whether
+        # this task is currently repairing such an exception, while this one only
+        # tests if it could (usually, the difference is whether this task is
+        # running)
+        #
+        # @return [Boolean]
+        def can_repair_error?(exception)
+            return if finished?
+
+            exception = exception.to_execution_exception
+            repaired_tasks.each do |repaired|
+                matchers = repaired[self, ErrorHandling]
+                if matchers.any? { |m| m === exception }
+                    return true
+                end
+            end
+            false
+        end
+
+        # Tests whether the given exception is handled by this task or by a
+        # repair handler attached to this task
+        def repairs_error?(exception)
+            exception = exception.to_execution_exception
+            running? && can_repair_error?(exception)
+        end
+
+        # Returns the set of repair tasks attached to self that match the given
+        # exception
+        def find_all_matching_repair_tasks(exception)
+            exception = exception.to_execution_exception
+            result = []
+            each_error_handler do |child, matchers|
+                next if child.finished?
+                result << child if matchers.any? { |m| m === exception }
+            end
+            result
+        end
+
+        # Tests if this task can handle the provided exception, either because
+        # it is an error repair task itself, or because it has one attached.
+        #
+        # It is different from {#handles_error?} as the latter tests whether
+        # this task is currently handling the exception, while this one only
+        # tests if it could (usually, the difference is whether this task is
+        # running)
+        #
+        # @return [Boolean]
+        def can_handle_error?(exception)
+            exception = exception.to_execution_exception
+            can_repair_error?(exception) ||
+                !find_all_matching_repair_tasks(exception).empty?
+        end
+
+        # Tests if this task is currently handling the provided exception,
+        # either because it is an error repair task itself, or because it has
+        # one attached.
+        #
+        # @return [Boolean]
+        def handles_error?(exception)
+            return if !plan
+            exception = exception.to_execution_exception
+            ((running? || starting?) && can_repair_error?(exception)) ||
+                find_all_matching_repair_tasks(exception).any? { |t| t.starting? || t.running? }
+        end
+
+        # Test if this task has an active repair tasks associated
+        def being_repaired?
+            each_child_object(ErrorHandling).any? { |t| t.running? }
+        end
+    end
+
+    class ErrorHandling
+        def merge_info(parent, child, opt1, opt2)
+            opt1 | opt2
+        end
+    end
+end
+

data/lib/roby/task_structure/executed_by.rb

@@ -0,0 +1,234 @@
+module Roby
+    module TaskStructure
+        # The execution_agent defines an agent (process or otherwise) a given
+        # task is executed by. It allows to define a class of these execution agent,
+        # so that the specific agents are managed externally (load-balancing, ...)
+        relation :ExecutionAgent,
+            parent_name: :executed_task,
+            child_name: :execution_agent,
+            noinfo: true,
+            distribute: false,
+            single_child: true,
+            copy_on_replace: true,
+            strong: true
+
+        class ExecutedTaskAlreadyRunning < RuntimeError; end
+
+        class ExecutionAgent
+            def self.execution_agent_failed_to_start(reason, ready_event)
+                execution_agent = ready_event.task
+
+                tasks = []
+                execution_agent.each_executed_task do |task|
+                    tasks << task
+                end
+
+                plan = execution_agent.plan
+                if !tasks.empty?
+                    plan.control.execution_agent_failed_to_start(execution_agent, tasks, reason)
+                end
+            end
+
+            def self.pending_execution_agent_failed(event)
+                execution_agent = event.task
+
+                if execution_agent.ready?
+                    tasks = []
+                    execution_agent.each_executed_task do |task|
+                        tasks << task if task.pending? || task.starting?
+                    end
+                    
+                    plan = execution_agent.plan
+                    if !tasks.empty?
+                        plan.control.pending_executed_by_failed(execution_agent, tasks)
+                    end
+                end
+            end
+
+            def self.remove_agent_aborted_relation(ev)
+                executed_task = ev.task
+                execution_agent = executed_task.execution_agent
+
+                # The event handler will be called even if the
+                # execution agent has been removed. Check that there is
+                # actually an execution agent 
+                if execution_agent
+                    execution_agent.stop_event.remove_forwarding executed_task.aborted_event
+                    executed_task.remove_execution_agent execution_agent
+                end
+            end
+
+            def self.establish_agent_aborted_relation(ev)
+                executed_task = ev.task
+                execution_agent = executed_task.execution_agent
+
+                # The event handler will be called even if the
+                # execution agent has been removed. Check that there is
+                # actually an execution agent 
+                if execution_agent
+                    execution_agent.stop_event.forward_to executed_task.aborted_event
+                end
+            end
+
+            # This module defines model-level definition of execution agent, for
+            # instance to Roby::Task
+            module ModelExtension
+                # The model of execution agent for this class
+                def execution_agent
+                    for klass in ancestors
+                        if klass.instance_variable_defined?(:@execution_agent)
+                            return klass.instance_variable_get(:@execution_agent)
+                        end
+                    end
+                    nil
+                end
+
+                # Defines a model of execution agent. Doing
+                #
+                #   TaskModel.executed_by ExecutionAgentModel
+                #
+                # is equivalent to
+                #
+                #   task = TaskModel.new
+                #   exec = <find a suitable ExecutionAgentModel instance in the plan or
+                #          create a new one>
+                #   task.executed_by exec
+                #   
+                # for all instances of TaskModel. The actual job is done in the
+                # ExecutionAgentSpawn module
+                def executed_by(agent_model, arguments = Hash.new)
+                    @execution_agent = [agent_model, arguments]
+                end
+            end
+
+            module Extension
+                # In order to handle faults, it is needed that some event handlers are
+                # defined on the task that has an execution agent
+                #
+                # However, we only want to define them once. Therefore, this flag is set
+                # to true as soon as the handlers have been added on +self+
+                attr_predicate :used_with_an_execution_agent?, true
+
+                # In order to handle faults, it is needed that some event handlers are
+                # defined on the agent's task
+                #
+                # However, we only want to define them once. Therefore, this flag is set
+                # to true as soon as the handlers have been added on +self+
+                attr_predicate :used_as_execution_agent?, true
+
+                # Defines a new execution agent for this task.
+                def executed_by(agent)
+                    if agent.respond_to?(:as_plan)
+                        agent = agent.as_plan
+                    end
+
+                    return if execution_agent == agent
+
+                    if !agent.has_event?(:ready)
+                        raise ArgumentError, "execution agent tasks should define the :ready event"
+                    end
+
+                    old_agent = execution_agent
+                    if old_agent && old_agent != agent
+                        remove_execution_agent old_agent
+                    end
+
+                    add_execution_agent(agent)
+                    agent
+                end
+
+                def adding_execution_agent(child, info)
+                    if running?
+                        raise ExecutedTaskAlreadyRunning, "#{self} is already running, cannot add or change its agent"
+                    end
+
+                    super
+
+                    if model_agent = model.execution_agent
+                        if !child.fullfills?(*model_agent)
+                            raise Roby::ModelViolation, "execution agent #{child} does not fullfill the expected #{model_agent}"
+                        end
+                    end
+                end
+
+                # Installs the handlers needed for fault handling
+                #
+                # See the documentation of #used_with_an_execution_agent?
+                def added_execution_agent(child, info)
+                    super
+                    if !used_with_an_execution_agent?
+                        start_event.on(&ExecutionAgent.method(:establish_agent_aborted_relation))
+                        stop_event.on(&ExecutionAgent.method(:remove_agent_aborted_relation))
+                        self.used_with_an_execution_agent = true
+
+                    end
+                    if !child.used_as_execution_agent?
+                        if !child.ready_event.emitted?
+                            child.ready_event.when_unreachable(
+                                true, &ExecutionAgent.method(:execution_agent_failed_to_start))
+                        end
+                        child.stop_event.on(
+                            &ExecutionAgent.method(:pending_execution_agent_failed))
+                        child.used_as_execution_agent = true
+                    end
+                end
+            end
+        end
+
+        class MissingRequiredExecutionAgent < Roby::CommandFailed
+            def initialize(task)
+                super(nil, task.start_event)
+            end
+            def pretty_print(pp)
+                pp.text "attempted to start a task that is expecting an execution agent but has none"
+                pp.breakable
+                failed_task.pretty_print(pp)
+            end
+        end
+
+        class ExecutionAgentNotReady < Roby::CommandFailed
+            attr_reader :execution_agent
+            def initialize(task)
+                super(nil, task.start_event)
+                @execution_agent = task.execution_agent
+            end
+            def pretty_print(pp)
+                pp.text "attempted to start a task buts its agent is not ready"
+                pp.breakable
+                failed_task.pretty_print(pp)
+                pp.breakable
+                pp.text "executed_by "
+                execution_agent.pretty_print(pp)
+            end
+        end
+
+        # This module is hooked in Roby::TaskEventGenerator to check that a task
+        # which is being started has a suitable execution agent, and to start it if
+        # it's not the case
+        module ExecutionAgentStart
+            module Installer
+                def initialize_events
+                    super
+                    start_event.extend ExecutionAgentStart
+                end
+            end
+            Roby::Task.class_eval do
+                prepend Installer
+            end
+
+            def calling(context)
+                super
+
+                agent = task.execution_agent
+                if !agent
+                    if task.model.execution_agent
+                        raise MissingRequiredExecutionAgent.new(task), "the model of #{task} requires an execution agent, but the task has none"
+                    end
+                elsif !agent.ready?
+                    raise ExecutionAgentNotReady.new(task), "cannot start #{task}, its agent is not ready"
+                end
+            end
+        end
+    end
+end
+

data/lib/roby/task_structure/planned_by.rb

@@ -0,0 +1,90 @@
+module Roby::TaskStructure
+    relation :PlannedBy,
+        child_name: :planning_task, 
+        parent_name: :planned_task,
+        noinfo: true,
+        single_child: true
+
+    class PlannedBy
+        module Extension
+            # Returns the first child enumerated by planned_tasks. This is a
+            # convenience method that can be used if it is known that the planning
+            # task is only planning for one single task (a pretty common case)
+            def planned_task
+                each_in_neighbour_merged(PlannedBy, intrusive: true).first
+            end
+            # The set of tasks which are planned by this one
+            def planned_tasks; parent_objects(PlannedBy) end
+            # Set +task+ as the planning task of +self+
+            def planned_by(task, replace: false, optional: false, plan_early: true)
+                if task.respond_to?(:as_plan)
+                    task = task.as_plan
+                end
+
+                if old = planning_task
+                    if replace
+                        remove_planning_task(old)
+                    else
+                        raise ArgumentError, "this task already has a planner"
+                    end
+                end
+                add_planning_task(task, optional: optional, plan_early: true)
+                if !plan_early
+                    task.schedule_as(self)
+                end
+
+                task
+            end
+        end
+
+        # Returns a set of PlanningFailedError exceptions for all abstract tasks
+        # for which planning has failed
+        def check_structure(plan)
+            result = []
+            each_edge do |planned_task, planning_task, options|
+                next if plan != planning_task.plan
+                next if !planning_task.failed?
+                next if !planned_task.self_owned?
+
+                if (planned_task.pending? && !planned_task.executable?) || !options[:optional]
+                    result << [Roby::PlanningFailedError.new(planned_task, planning_task), nil]
+                end
+            end
+
+            result
+        end
+    end
+end
+
+module Roby
+    # This exception is raised when a task is abstract, and its planner failed:
+    # the system will therefore not have a suitable executable development for
+    # this task, and this is a failure
+    class PlanningFailedError < LocalizedError
+        # The planning task
+        attr_reader :planning_task
+        # The planned task
+        def planned_task; failed_task end
+        # The reason for the failure
+        attr_reader :failure_reason
+
+        def initialize(planned_task, planning_task, failure_reason: planning_task.failure_reason)
+            super(planned_task)
+            @planning_task = planning_task
+            @failure_reason = failure_reason
+            report_exceptions_from(failure_reason)
+        end
+
+        def pretty_print(pp)
+            pp.text "failed to plan "
+            planned_task.pretty_print(pp)
+            pp.breakable
+            pp.text "planned by "
+            planning_task.pretty_print(pp)
+            pp.breakable
+            pp.text " failed with "
+            failure_reason.pretty_print(pp)
+        end
+    end
+end
+

data/lib/roby/tasks/aggregator.rb

@@ -0,0 +1,37 @@
+module Roby::Tasks
+    # Base functionality for the Sequence and Parallel aggregators
+    class TaskAggregator < Roby::Task
+        def initialize(arguments = Hash.new)
+            @tasks = Array.new
+            @name = nil
+            super
+        end
+
+        terminates
+        event(:start, controlable: true)
+
+        # The array of tasks that are aggregated by this object
+        attr_reader :tasks
+
+        # TODO: is this really necessary
+        def each_task(&iterator)
+            yield(self)
+            tasks.each(&iterator) 
+        end
+
+        # True if this aggregator has no tasks
+        def empty?; tasks.empty? end
+
+        # Removes this aggregator from the plan
+        def delete
+            @name  = self.name
+            @tasks = nil
+            if plan
+                plan.remove_task(self)
+            else
+                clear_relations
+                freeze 
+            end
+        end
+    end
+end