roby 0.8.0 → 3.0.0

data/lib/roby/coordination/models/arguments.rb

@@ -0,0 +1,55 @@
+module Roby
+    module Coordination
+        module Models
+            module Arguments
+                extend MetaRuby::Attributes
+
+                Argument = Struct.new :name, :required, :default
+
+                # The set of arguments available to this execution context
+                # @return [Array<Symbol>]
+                inherited_attribute(:argument, :arguments, map: true) { Hash.new }
+
+                # Define a new argument for this coordination model
+                #
+                # Arguments are made available within the coordination model as
+                # Variable objects
+                #
+                # @param [String,Symbol] name the argument name
+                # @param [Hash] options
+                # @option options :default a default value for this argument. Note
+                #   that 'nil' is considered as a proper default value.
+                # @return [Argument] the new argument object
+                def argument(name, options = Hash.new)
+                    options = Kernel.validate_options options, :default
+                    arguments[name.to_sym] = Argument.new(name.to_sym, !options.has_key?(:default), options[:default])
+                end
+
+                # Validates that the provided argument hash is valid for this
+                # particular coordination model
+                #
+                # @raise ArgumentError if some given arguments are not known to this
+                #   model, or if some required arguments are not set
+                def validate_arguments(arguments)
+                    arguments = Kernel.normalize_options arguments
+                    arguments.keys.each do |arg_name|
+                        if !find_argument(arg_name)
+                            raise ArgumentError, "#{arg_name} is not an argument on #{self}"
+                        end
+                    end
+                    each_argument do |_, arg|
+                        if !arguments.has_key?(arg.name)
+                            if arg.required
+                                raise ArgumentError, "#{arg.name} is required by #{self}, but is not provided (given arguments: #{arguments})"
+                            end
+                            arguments[arg.name] = arg.default
+                        end
+                    end
+                    arguments
+                end
+            end
+        end
+    end
+end
+
+

data/lib/roby/coordination/models/base.rb

@@ -0,0 +1,176 @@
+module Roby
+    module Coordination
+        module Models
+        # Model part of Base
+        module Base
+            include MetaRuby::ModelAsClass
+            include Arguments
+
+            # Name of this coordination object
+            #
+            # For debugging purposes. It is usually set by the enclosing context
+            #
+            # @return [String,nil]
+            attr_accessor :name
+
+            # Gets or sets the root task model
+            #
+            # @return [Root] the root task model, i.e. a representation of the
+            #   task this execution context is going to be run on
+            def root(*new_root)
+                if !new_root.empty?
+                    @root = Root.new(new_root.first, self)
+                elsif @root then @root
+                elsif superclass.respond_to?(:root)
+                    @root = superclass.root.rebind(self)
+                end
+            end
+
+            # @deprecated use {#root} instead, as it is a more DSL-like API
+            attr_writer :root
+
+            # @return [Model<Roby::Task>] the task model this execution context
+            #   is attached to
+            def task_model; root.model end
+
+            # Gives direct access to the root's events
+            #
+            # This is needed to be able to use a coordination model as model for
+            # a coordination task, which in turn gives access to e.g. states in
+            # an action state machine
+            def find_event(name)
+                root.find_event(name)
+            end
+
+            # Returns the task for the given name, if found, nil otherwise
+            #
+            # @return Roby::Coordination::Models::TaskFromAction
+            def find_task_by_name(name)
+                tasks.find do |m|
+                    m.name == name.to_s
+                end
+            end
+
+            # The set of defined tasks
+            # @return [Array<Task>]
+            inherited_attribute(:task, :tasks) { Array.new }
+
+            # The set of fault response tables that should be active when this
+            # coordination model is
+            # @return [Array<(FaultResponseTable,Hash)>]
+            inherited_attribute(:used_fault_response_table, :used_fault_response_tables) { Array.new }
+
+            # Creates a new execution context model as a submodel of self
+            #
+            # @param [Model<Roby::Task>] subclass the
+            #   task model that is going to be used as a toplevel task for the
+            #   state machine
+            # @return [Model<StateMachine>] a subclass of StateMachine
+            def setup_submodel(subclass, options = Hash.new)
+                options = Kernel.validate_options options, root: Roby::Task
+                subclass.root(options[:root])
+                super
+            end
+
+            # Creates a state from an object
+            def task(object, task_model = Roby::Task)
+                if object.respond_to?(:to_coordination_task)
+                    task = object.to_coordination_task(task_model)
+                    tasks << task
+                    task
+                elsif object.respond_to?(:as_plan)
+                    task = TaskFromAsPlan.new(object, task_model)
+                    tasks << task
+                    task
+                else raise ArgumentError, "cannot create a task from #{object}"
+                end
+            end
+
+            # @api private
+            #
+            # Transform the model by exchanging tasks
+            #
+            # @param [#[]] mapping a mapping that replaces an existing task by a
+            #   new one. All tasks must be mapped
+            def map_tasks(mapping)
+                @root  = mapping.fetch(root)
+                @tasks = tasks.map do |t|
+                    new_task = mapping.fetch(t)
+                    new_task.map_tasks(mapping)
+                    new_task
+                end
+            end
+
+            # Assigns names to tasks based on the name of the local variables
+            # they are assigned to
+            #
+            # This must be called by methods that are themselves called during
+            # parsing
+            #
+            # @param [String] suffix that should be added to all the names
+            def parse_names(suffixes)
+                definition_context = binding.callers.find { |b| b.frame_type == :block }
+                return if !definition_context
+
+                # Assign names to tasks using the local variables
+                vars = definition_context.eval "local_variables"
+                values = definition_context.eval "[#{vars.map { |n| "#{n}" }.join(", ")}]"
+                vars.zip(values).each do |name, object|
+                    suffixes.each do |klass, suffix|
+                        if object.kind_of?(klass)
+                            object.name = "#{name}#{suffix}"
+                        end
+                    end
+                end
+            end
+
+            def respond_to_missing?(m, include_private)
+                has_argument?(m) ||
+                    (m =~ /_event$|_child$/ && root.respond_to?(m)) ||
+                    super
+            end
+
+            def method_missing(m, *args, &block)
+                if has_argument?(m)
+                    if !args.empty?
+                        raise ArgumentError, "expected zero arguments to #{m}, got #{args.size}"
+                    end
+                    Variable.new(m)
+                elsif m =~ /(.*)(?:_event$|_child$)/
+                    return root.send(m, *args, &block)
+                else return super
+                end
+            end
+
+            def validate_task(object)
+                if !object.kind_of?(Coordination::Models::Task)
+                    raise ArgumentError, "expected a state object, got #{object}. States need to be created from e.g. actions by calling #state before they can be used in the state machine"
+                end
+                object
+            end
+
+            def validate_or_create_task(task)
+                if !task.kind_of?(Coordination::Models::Task)
+                    task(task)
+                else task
+                end
+            end
+
+            def validate_event(object)
+                if !object.kind_of?(Coordination::Models::Event)
+                    raise ArgumentError, "expected an action-event object, got #{object}. Acceptable events need to be created from e.g. actions by calling #task(action).my_event"
+                end
+                object
+            end
+
+            # Declare that this fault response table should be active as long as
+            # this coordination model is
+            def use_fault_response_table(table_model, arguments = Hash.new)
+                arguments = table_model.validate_arguments(arguments)
+                used_fault_response_tables << [table_model, arguments]
+            end
+        end
+        end
+    end
+end
+

data/lib/roby/coordination/models/capture.rb

@@ -0,0 +1,86 @@
+module Roby
+    module Coordination
+        module Models
+            # Object that is used to represent the context of an event context
+            class Capture
+                # The capture name
+                #
+                # Only used for debugging purposes
+                #
+                # @return [String]
+                attr_accessor :name
+
+                # Create a new capture object
+                #
+                # @param [#call] filter an object that is used to process the
+                #   event's context. It is passed the context as-is (i.e. as an
+                #   array) and should return the value that should be captured
+                def initialize(filter = lambda { |event| event.context })
+                    @filter = filter
+                end
+
+                # Filter the context through the filter object passed to
+                # {#initialize}
+                def filter(state_machine, event)
+                    CaptureEvaluationContext.new(state_machine).
+                        instance_exec(event, &@filter)
+                end
+
+                class CaptureEvaluationContext < Object
+                    def initialize(state_machine)
+                        @state_machine = state_machine
+                    end
+
+                    def respond_to_missing?(m, include_private)
+                        @state_machine.model.has_argument?(m) || super
+                    end
+
+                    def method_missing(m, *args)
+                        if @state_machine.arguments.has_key?(m)
+                            if args.empty?
+                                return @state_machine.arguments[m]
+                            else
+                                raise ArgumentError, "expected zero argument to #{m}, got #{args.size}"
+                            end
+                        elsif @state_machine.model.has_argument?(m)
+                            raise ArgumentError, "#{m} is not set"
+                        end
+                        super
+                    end
+                end
+
+                # Exception raised when trying to evaluate a capture whose
+                # backing event has not yet happened
+                class Unbound < RuntimeError
+                    attr_reader :capture
+                    def initialize(capture)
+                        @capture = capture
+                    end
+                end
+
+                def evaluate_delayed_argument(task)
+                    throw :no_value
+                end
+
+                # Evaluate the capture
+                #
+                # @param [Hash] variables the underlying coordination object's
+                #   bound variables
+                # @raise Unbound if the capture's backing event has not yet been
+                #   emitted
+                def evaluate(variables)
+                    if variables.has_key?(self)
+                        variables[self]
+                    else
+                        raise Unbound.new(self), "#{self} is not bound yet"
+                    end
+                end
+
+                def to_s
+                    "capture:#{name || '<unnamed>'}"
+                end
+            end
+        end
+    end
+end
+

data/lib/roby/coordination/models/child.rb

@@ -0,0 +1,35 @@
+module Roby
+    module Coordination
+        module Models
+            # A representation of a task of the execution context's task
+            class Child < Task
+                # @return [Base,Child] the child's parent
+                attr_reader :parent
+                # @return [String] the child's role, relative to its parent
+                attr_reader :role
+                # The child's model
+                attr_reader :model
+
+                def initialize(parent, role, model)
+                    @parent, @role, @model = parent, role, model
+                end
+
+                def ==(other)
+                    other.kind_of?(Child) &&
+                        other.parent == parent &&
+                        other.role == role &&
+                        other.model == model
+                end
+
+                # @return [Coordination::Child]
+                def new(execution_context)
+                    Coordination::Child.new(execution_context, self)
+                end
+
+                def to_s; "#{parent}.#{role}_child[#{model}]" end
+            end
+        end
+    end
+end
+
+

data/lib/roby/coordination/models/event.rb

@@ -0,0 +1,41 @@
+module Roby
+    module Coordination
+        module Models
+            # A representation of an event on the execution context's task
+            class Event
+                # @return [Coordination::Models::Task] The task this event is defined on
+                attr_reader :task
+                # @return [Symbol] the event's symbol
+                attr_reader :symbol
+
+                def initialize(task, symbol)
+                    @task, @symbol = task, symbol.to_sym
+                end
+
+                # @return [Coordination::Base::Event]
+                def new(execution_context)
+                    Coordination::Event.new(execution_context, self)
+                end
+
+                def ==(other)
+                    other.kind_of?(self.class) &&
+                        other.symbol == symbol &&
+                        other.task == task
+                end
+
+                # When running in this event's state, forward this event to the
+                # given root task event
+                def forward_to(root_event)
+                    if !root_event.task.respond_to?(:coordination_model)
+                        raise NotRootEvent, "can only forward to a root event"
+                    end
+                    root_event.task.coordination_model.
+                        forward task, self, root_event
+                end
+
+                def to_s; "#{task}.#{symbol}_event" end
+            end
+        end
+    end
+end
+

data/lib/roby/coordination/models/exceptions.rb

@@ -0,0 +1,42 @@
+module Roby
+    module Coordination
+        module Models
+            # Base class for model validation errors
+            class CoordinationModelError < Exception; end
+
+            # Exception thrown when using a non-root event in a context where
+            # only root events are allowed
+            class NotRootEvent < CoordinationModelError; end
+
+            # Exception raised in state machine definitions when a state is used
+            # in a transition, that cannot be reached in the first place
+            class UnreachableStateUsed < RuntimeError
+                # The set of unreachable states
+                attr_reader :states
+
+                def initialize(states)
+                    @states = states
+                end
+
+                def pretty_print(pp)
+                    pp.text "#{states.size} states are unreachable but used in transitions anyways"
+                    pp.nest(2) do
+                        pp.seplist(states) do |s|
+                            pp.breakable
+                            s.pretty_print(pp)
+                        end
+                    end
+                end
+            end
+
+            # Exception thrown when a toplevel state was expected but a
+            # dependency was given
+            class NotToplevelState < CoordinationModelError; end
+
+            # Exception thrown when using an event in a context where it is not
+            # active
+            class EventNotActiveInState < CoordinationModelError; end
+        end
+    end
+end
+

data/lib/roby/coordination/models/fault_handler.rb

@@ -0,0 +1,219 @@
+module Roby
+    module Coordination
+        module Models
+            # Definition of a single fault handler in a FaultResponseTable
+            module FaultHandler
+                include Actions
+                include Script
+
+                # @return [FaultResponseTable] the table this handler is part of
+                def fault_response_table; action_interface end
+                # @return [Queries::ExecutionExceptionMatcher] the object
+                #   defining for which faults this handler should be activated
+                inherited_single_value_attribute(:execution_exception_matcher) { Queries.none }
+                # @return [Integer] this handler's priority
+                inherited_single_value_attribute(:priority) { 0 }
+                # @return [:missions,:actions,:origin] the fault response
+                #   location
+                inherited_single_value_attribute(:response_location) { :actions }
+                # @return [Boolean] if true, the action location will be retried
+                #   after the fault response table, otherwise whatever should
+                #   happen will happen (other error handling, ...)
+                inherited_single_value_attribute(:__carry_on) { false }
+                # @return [Boolean] if true, the last action of the response
+                #   will be to retry whichever action/missions/tasks have been
+                #   interrupted by the fault
+                def carry_on?; !!__carry_on end
+                # @deprecated use {#carry_on?}
+                def try_again?; carry_on? end
+                # @return [#instanciate] an object that allows to create the
+                #   toplevel task of the fault response
+                inherited_single_value_attribute :action
+
+                def to_s
+                    "#{fault_response_table}.on_fault(#{execution_exception_matcher})"
+                end
+
+                def locate_on_missions
+                    response_location :missions
+                    self
+                end
+
+                def locate_on_actions
+                    response_location :actions
+                    self
+                end
+
+                def locate_on_origin
+                    response_location :origin
+                    self
+                end
+
+                # Try the repaired action again when the fault handler
+                # successfully finishes
+                #
+                # It can be called anytime in the script, but will have an
+                # effect only at the end of the fault handler
+                def carry_on
+                    __carry_on(true)
+                    terminal
+                end
+
+                # @deprecated use {#carry_on}
+                def try_again; carry_on end
+
+                # Script element that implements the replacement part of
+                # {#replace_by}
+                class ReplaceBy < Coordination::ScriptInstruction
+                    attr_reader :replacement_task
+
+                    def initialize(replacement_task)
+                        @replacement_task = replacement_task
+                    end
+
+                    def new(fault_handler)
+                        ReplaceBy.new(fault_handler.instance_for(replacement_task))
+                    end
+
+                    def execute(fault_handler)
+                        response_task = fault_handler.root_task
+                        plan = response_task.plan
+                        replacement_task = self.replacement_task.resolve
+
+                        response_task.each_parent_object(Roby::TaskStructure::ErrorHandling) do |repaired_task|
+                            repaired_task_parents = repaired_task.each_parent_task.map do |parent_task|
+                                [parent_task, parent_task[repaired_task, Roby::TaskStructure::Dependency]]
+                            end
+                            plan.replace(repaired_task, replacement_task)
+                            repaired_task_parents.each do |parent_t, dependency_options|
+                                parent_t.add_child repaired_task, dependency_options
+                            end
+                        end
+                        true
+                    end
+
+                    def to_s; "start(#{task}, #{dependency_options})" end
+                end
+
+                class FinalizeReplacement < Coordination::ScriptInstruction
+                    def new(fault_handler)
+                        self
+                    end
+
+                    def execute(fault_handler)
+                        response_task = fault_handler.root_task
+                        response_task.each_parent_object(Roby::TaskStructure::ErrorHandling) do |repaired_task|
+                            repaired_task_parents = repaired_task.each_parent_task.to_a
+                            repaired_task_parents.each do |parent|
+                                parent.remove_child repaired_task
+                            end
+                        end
+                    end
+                end
+
+                # Replace the response's location by this task when the fault
+                # handler script is finished
+                #
+                # It terminates the script, i.e. no instructions can be added
+                # after it is called
+                #
+                # @raise ArgumentError if there is already a replacement task
+                def replace_by(task, until_event = nil)
+                    __carry_on(false)
+                    replacement_task = validate_or_create_task(task)
+                    start replacement_task
+                    instructions << ReplaceBy.new(replacement_task)
+                    wait(until_event || replacement_task.success_event)
+                    instructions << FinalizeReplacement.new
+                    emit success_event
+                    terminal
+                end
+
+                class ResponseLocationVisitor < RGL::DFSVisitor
+                    attr_reader :predicate, :selected
+
+                    def initialize(graph, predicate)
+                        super(graph)
+                        @predicate = predicate
+                        @selected = Set.new
+                    end
+
+                    def handle_examine_vertex(u)
+                        if predicate.call(u)
+                            selected << u
+                        end
+                    end
+
+                    def follow_edge?(u, v)
+                        if selected.include?(u)
+                            false
+                        else super
+                        end
+                    end
+                end
+
+                def find_response_locations(origin)
+                    if response_location == :origin
+                        return [origin].to_set
+                    end
+
+                    predicate =
+                        if response_location == :missions
+                            proc { |t| t.mission? && t.running? }
+                        elsif response_location == :actions
+                            proc { |t| t.running? && t.planning_task && t.planning_task.kind_of?(Roby::Actions::Task) }
+                        end
+
+                    search_graph = origin.plan.
+                        task_relation_graph_for(TaskStructure::Dependency).
+                        reverse
+                    visitor = ResponseLocationVisitor.new(search_graph, predicate)
+                    search_graph.depth_first_visit(origin, visitor) {}
+                    visitor.selected
+                end
+
+                # @api private
+                #
+                # Activate this fault handler for the given exception and
+                # arguments. It creates the {FaultHandlingTask} and attaches the
+                # handler on it as an action script.
+                #
+                # @param [ExecutionException] exception
+                # @param [Hash] arguments
+                def activate(exception, arguments = Hash.new)
+                    locations = find_response_locations(exception.origin)
+                    if locations.empty?
+                        Roby.warn "#{self} did match an exception, but the response location #{response_location} does not match anything"
+                        return
+                    end
+
+                    plan = exception.origin.plan
+
+                    # Create the response task
+                    plan.add(response_task = FaultHandlingTask.new)
+                    response_task.fault_handler = self
+                    new(response_task, arguments)
+                    response_task.start!
+                    locations.each do |task|
+                        # Mark :stop as handled by the response task and kill
+                        # the task
+                        #
+                        # In addition, if origin == task, we need to handle the
+                        # error events as well
+                        task.add_error_handler response_task,
+                            [task.stop_event.to_execution_exception_matcher, execution_exception_matcher].to_set
+                    end
+                    locations.each do |task|
+                        # This should not be needed. However, the current GC
+                        # implementation in ExecutionEngine does not stop at
+                        # finished tasks, and therefore would not GC the
+                        # underlying tasks
+                        task.remove_children(Roby::TaskStructure::Dependency)
+                        task.stop! if task.running?
+                    end
+                end
+            end
+        end
+    end
+end
+