roby 0.8.0 → 3.0.0

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

@@ -0,0 +1,77 @@
+module Roby
+    module Coordination
+        module Models
+            # Definition of the metamodel for Coordination::FaultResponseTable
+            module FaultResponseTable
+                include Roby::Actions::Models::Interface
+                include Arguments
+
+                # The set of defined fault handlers
+                #
+                # @return [FaultHandler]
+                inherited_attribute('fault_handler', 'fault_handlers') { Array.new }
+
+                def find_all_matching_handlers(exception)
+                    each_fault_handler.find_all do |h|
+                        h.execution_exception_matcher === exception
+                    end
+                end
+
+                # Representation of a fault handler at the interface level
+                class Action < Roby::Actions::Models::Action
+                    attr_reader :fault_response_table_model
+
+                    # The fault handler model itself
+                    def fault_handler_model
+                        coordination_model
+                    end
+
+                    # The common interface to set the fault handler
+                    attr_accessor :coordination_model
+
+                    def initialize(fault_response_table_model)
+                        super()
+                        @fault_response_table_model = fault_response_table_model
+                    end
+                end
+
+                def on_fault(exception_matcher, &block)
+                    exception_matcher = exception_matcher.to_execution_exception_matcher
+                    action_model = Action.new(self)
+                    each_argument do |_, arg|
+                        action_model.required_arg(arg.name)
+                    end
+                    action_model, handler =
+                        create_coordination_action(action_model, Coordination::FaultHandler, &block)
+                    handler.execution_exception_matcher(exception_matcher)
+                    fault_handlers << handler
+                    handler
+                end
+
+                def each_task
+                    return enum_for(:each_task) if !block_given?
+                    super
+                    each_fault_handler do |handler|
+                        if task = handler.replacement
+                            yield(task)
+                        end
+                    end
+                end
+
+                def respond_to_missing?(m, include_private)
+                    Queries::ExecutionExceptionMatcher.method_defined?(m) || super
+                end
+
+                def method_missing(m, *args, &block)
+                    if Queries::ExecutionExceptionMatcher.method_defined?(m)
+                        matcher = Queries::ExecutionExceptionMatcher.new
+                        matcher.send(m, *args, &block)
+                        matcher
+                    else super
+                    end
+                end
+            end
+        end
+    end
+end
+

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

@@ -0,0 +1,22 @@
+module Roby
+    module Coordination
+        module Models
+            # The root task in the execution context
+            class Root < Task
+                attr_accessor :coordination_model
+
+                def initialize(model, coordination_model)
+                    super(model)
+                    @coordination_model = coordination_model
+                end
+
+                def rebind(coordination_model)
+                    m = super
+                    m.coordination_model = coordination_model
+                    m
+                end
+            end
+        end
+    end
+end
+

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

@@ -0,0 +1,283 @@
+require 'roby/tasks/timeout'
+module Roby
+    module Coordination
+        module Models
+            # The metamodel for all script-based coordination models
+            module Script
+                extend MetaRuby::Attributes
+
+                class DeadInstruction < Roby::LocalizedError; end
+
+                # Script element that implements {Script#start}
+                class Start < Coordination::ScriptInstruction
+                    attr_reader :task
+                    attr_reader :dependency_options
+
+                    attr_predicate :explicit_start?, true
+
+                    def initialize(task, explicit_start: false, **dependency_options)
+                        @explicit_start = explicit_start
+                        @task = task
+                        @dependency_options = dependency_options
+                    end
+
+                    def new(script)
+                        Start.new(script.instance_for(task), explicit_start: explicit_start?, **dependency_options)
+                    end
+
+                    def execute(script)
+                        script.start_task(task, explicit_start: explicit_start?)
+                        true
+                    end
+
+                    def to_s; "start(#{task}, #{dependency_options})" end
+                end
+
+                # Script element that implements {Script#wait}
+                class Wait < Coordination::ScriptInstruction
+                    attr_reader :event
+
+                    # @return [Time,nil] time after which an emission is valid.
+                    #   'nil' means that only emissions that have happened after
+                    #   the script reached this instruction are considered
+                    attr_reader :time_barrier
+
+                    # @return [Float] number of seconds after which the wait
+                    #   instruction should generate an error
+                    attr_reader :timeout
+
+                    # @return [Boolean] true if {#execute} has been called once
+                    attr_predicate :initialized?
+
+                    # @return [Boolean] true if the watched event got emitted
+                    attr_predicate :done?
+
+                    # @option options [Float] :timeout (nil) value for {#timeout}
+                    # @option options [Time] :after (nil) value for
+                    #   {#time_barrier}
+                    def initialize(event, after: nil)
+                        @event = event
+                        @done = false
+                        @time_barrier = after
+                    end
+
+                    def new(script)
+                        Wait.new(script.instance_for(event), after: time_barrier)
+                    end
+
+                    def execute(script)
+                        event     = self.event.resolve
+                        plan      = script.plan
+                        root_task = script.root_task
+
+                        if time_barrier
+                            last_event = event.history.last
+                            if last_event && last_event.time > time_barrier
+                                return true
+                            end
+                        end
+
+                        if event.unreachable?
+                            plan.add_error(DeadInstruction.new(script.root_task))
+                            return false
+                        end
+
+                        if event.task != root_task
+                            role_name = "wait_#{self.object_id}"
+                            current_roles = (root_task.depends_on?(event.task) && root_task.roles_of(event.task))
+                            root_task.depends_on event.task, success: nil, role: role_name
+                        end
+
+                        event.if_unreachable(cancel_at_emission: true) do |reason, generator|
+                            if !disabled?
+                                generator.plan.add_error(DeadInstruction.new(script.root_task))
+                            end
+                        end
+
+                        event.on on_replace: :copy do |event|
+                            if event.generator == self.event.resolve && !disabled?
+                                if !time_barrier || event.time > time_barrier
+                                    if role_name && (child = script.root_task.find_child_from_role(role_name))
+                                        script.root_task.remove_roles(child, role_name, remove_child_when_empty: !current_roles || !current_roles.empty?)
+                                    end
+                                    cancel
+                                    script.step
+                                end
+                            end
+                        end
+
+                        false
+                    end
+
+                    def waited_task_role
+                        "wait_#{object_id}"
+                    end
+
+                    def to_s; "wait(#{event})" end
+                end
+
+                # Script element that implements {Script#emit}
+                class Emit < Coordination::ScriptInstruction
+                    # @return [Event] the event that should be
+                    # emitted
+                    attr_reader :event
+
+                    def initialize(event)
+                        @event = event
+                    end
+
+                    def new(script)
+                        Emit.new(script.instance_for(event))
+                    end
+
+                    def execute(script)
+                        event.resolve.emit
+                        true
+                    end
+
+                    def to_s; "emit(#{event})" end
+                end
+
+                class TimeoutStart
+                    attr_reader :seconds
+                    attr_reader :event
+
+                    def initialize(seconds, options = Hash.new)
+                        @seconds = seconds
+                        options = Kernel.validate_options options, emit: nil
+                        @event = options[:emit]
+                    end
+
+                    def new(script)
+                        event = if self.event
+                                    script.instance_for(self.event)
+                                end
+
+                        Coordination::TaskScript::TimeoutStart.new(self, event)
+                    end
+                end
+
+                class TimeoutStop
+                    attr_reader :timeout_start
+
+                    def initialize(timeout_start)
+                        @timeout_start = timeout_start
+                    end
+
+                    def new(script)
+                        Coordination::TaskScript::TimeoutStop.new(script.instance_for(timeout_start))
+                    end
+                end
+
+                inherited_single_value_attribute('__terminal') { false }
+
+                # Marks this script has being terminated, i.e. that no new
+                # instructions can be added to it
+                #
+                # Once this is called, adding new instructions will raise
+                # ArgumentError
+                def terminal
+                    __terminal(true)
+                end
+
+                # @return [Boolean] if true, this script cannot get new
+                #   instructions (a terminal instruction has been added)
+                def terminal?
+                    __terminal
+                end
+
+                # The list of instructions in this script
+                # @return [Array]
+                attribute(:instructions) { Array.new }
+
+                # Starts the given task
+                #
+                # @param [Task] task the action-task. It must be created by
+                #   calling {Base#task} on the relevant object
+                # @param [Hash] options the dependency relation options. See
+                #   {Roby::TaskStructure::Dependency::Extension#depends_on}
+                def start(task, explicit_start: false, **options)
+                    task = validate_or_create_task task
+                    add Start.new(task, explicit_start: explicit_start, **options)
+                    wait(task.start_event)
+                end
+
+                # Starts the given task, and waits for it to successfully finish
+                #
+                # @param [Task] task the action-task. It must be created by
+                #   calling {Base#task} on the relevant object
+                # @param [Hash] options the dependency relation options. See
+                #   {Roby::TaskStructure::Dependency::Extension#depends_on}
+                def execute(task, options = Hash.new)
+                    task = validate_or_create_task task
+                    start(task, options)
+                    wait(task.success_event)
+                end
+
+                # Waits a certain amount of time before continuing
+                #
+                # @param [Float] time the amount of time to wait, in seconds
+                def sleep(time)
+                    task = self.task(ActionCoordination::TaskFromAsPlan.new(Tasks::Timeout.with_arguments(delay: time), Tasks::Timeout))
+                    start task, explicit_start: true
+                    wait task.stop_event
+                end
+
+                # Waits until this event gets emitted
+                #
+                # It will wait even if this event has already been emitted at
+                # this point in the script (i.e. waits for a "new" emission)
+                #
+                # @param [Event] event the event to wait for
+                # @param [Hash] options
+                # @param [Float] timeout a timeout (for backward
+                #   compatibility, use timeout(seconds) do ... end instead)
+                def wait(event, timeout: nil, **wait_options)
+                    validate_event event
+
+                    wait = Wait.new(event, **wait_options)
+                    if timeout
+                        timeout(timeout) do
+                            add wait
+                        end
+                    else
+                        add wait
+                    end
+                    wait
+                end
+
+                # Emit the given event
+                #
+                # @param [Event] event
+                def emit(event)
+                    validate_event event
+                    add Emit.new(event)
+                end
+
+                # Execute another script at this point in the execution
+                def call(script)
+                    instructions.concat(script.instructions)
+                end
+
+                def timeout_start(delay, options = Hash.new)
+                    ins = TimeoutStart.new(delay, options)
+                    add ins
+                    ins
+                end
+
+                def timeout_stop(timeout_start)
+                    ins = TimeoutStop.new(timeout_start)
+                    add ins
+                    ins
+                end
+
+                def add(instruction)
+                    if terminal?
+                        raise ArgumentError, "a terminal command has been called on this script, cannot add anything further"
+                    end
+                    instructions << instruction
+                end
+            end
+        end
+    end
+end

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

@@ -0,0 +1,184 @@
+module Roby
+    module Coordination
+        module Models
+            # 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 class is the base class for all model-level coordination
+            # tasks. It is typed (i.e. we know the Roby task model that it
+            # represents) and optionally has a name.
+            class Task
+                # The underlying Roby task model
+                #
+                # If it responds to {#find_child}, the coordination task model
+                # will allow to validate the task's own children.
+                #
+                # @return [Model<Roby::Task>] the Roby task model, as a subclass
+                #   of Roby::Task
+                attr_accessor :model
+
+                # The task name
+                #
+                # @return [nil,String]
+                attr_accessor :name
+
+                # Creates this model-level coordination task to represent a
+                # given Roby task model
+                #
+                # @param [Model<Roby::Task>] model the Roby task model, which is
+                #   either Roby::Task or one of its subclasses
+                def initialize(model)
+                    @model = model
+                end
+
+                # Create a new coordination task based on a different
+                # coordination model
+                def rebind(coordination_model)
+                    dup
+                end
+
+                # @api private
+                #
+                # Used in {Base#rebind} to update the internal relationships
+                # between coordination tasks
+                def map_tasks(mapping)
+                end
+
+                # Returns an instance-level coordination task that can be used
+                # to represent self
+                #
+                # It is delegated to the task model, as the actual class that is
+                # used to represent self in a coordination object might depend
+                # on the class of the model-level coordination task.
+                #
+                # @return [Coordination::Task]
+                def new(execution_context)
+                    Coordination::Task.new(execution_context, self)
+                end
+
+                # Tests if this task has a given event
+                #
+                # @param [String,Symbol] event_name the event name
+                # @return [Boolean] true if the event is an event of self, and
+                #   false otherwise
+                def has_event?(event_name)
+                    if model && model.respond_to?(:find_event)
+                        model.find_event(event_name.to_sym)
+                    else true
+                    end
+                end
+
+                # Returns an model-level coordination event that can be used to
+                # represent an event on this task
+                #
+                # @param [String,Symbol] event_name the event name
+                # @return [Coordination::Models::Event] the event object, or nil
+                #   if the event does not exist
+                def find_event(event_name)
+                    if has_event?(event_name)
+                        return Event.new(self, event_name)
+                    end
+                end
+
+                # Test if this coordination task can tell us something about the
+                # models of its children
+                #
+                # It uses the presence or absence of a #find_child method on
+                # {#model} to determine it.
+                #
+                # @return [Boolean] true if {#has_child?} and
+                #   {#find_child_model} can return meaningful information.
+                def can_resolve_child_models?
+                    model && model.respond_to?(:find_child)
+                end
+
+                # Tests if this task has a child with the given role
+                #
+                # It always returns true if {#model} does not allow us to
+                # resolve children. The rationale is that these methods are used
+                # to type-validate tasks in e.g. action state machines and we
+                # need to simply be permissive if the models does not allow us
+                # to validate anything. Use {#can_resolve_child_models?} to know
+                # whether validation is meaningful.
+                #
+                # @return [Boolean] true if the task has a child with the given
+                #   role, or if {#model} does not allow to do any validation.
+                def has_child?(role)
+                    find_child_model(role) ||
+                        !can_resolve_child_models?
+                end
+
+                # Returns the model of a given child of this task
+                #
+                # It always returns Roby::Task if {#model} does not allow us to
+                # resolve children. The rationale is that these methods are used
+                # to type-validate tasks in e.g. action state machines and we
+                # need to simply be permissive if the models does not allow us
+                # to validate anything. Use {#can_resolve_child_models?} to know
+                # whether validation is meaningful.
+                #
+                # @return [Model<Roby::Task>,nil] the child's model, or nil if
+                #   the child does not exist.
+                def find_child_model(role)
+                    if can_resolve_child_models?
+                        model.find_child(role)
+                    end
+                end
+
+                # Returns a representation of this task's child that can be used
+                # in a coordination model
+                #
+                # @param [String,Symbol] role the child's role
+                # @param [nil,Model<Roby::Task>] child_model the child's model.
+                #   This can be set to either overwrite what is known to Roby
+                #   (i.e. overwrite what {#model} announces), or to give
+                #   information that {#model} does not have in case
+                #   {#can_resolve_child_models?} returns false
+                # @return [Coordination::Models::Child,nil] the child object, or
+                #   nil if there is no such child on self
+                def find_child(role, child_model = nil)
+                    if has_child?(role)
+                        return Child.new(self, role, child_model || find_child_model(role))
+                    end
+                end
+
+                def find_through_method_missing(m, args)
+                    MetaRuby::DSLs.find_through_method_missing(
+                        self, m, args,
+                        '_event' => :find_event,
+                        '_child' => :find_child) ||
+                        super
+                end
+
+                def has_through_method_missing?(m)
+                    MetaRuby::DSLs.has_through_method_missing?(
+                        self, m,
+                        '_event' => :has_event?,
+                        '_child' => :has_child?) ||
+                        super
+                end
+
+                include MetaRuby::DSLs::FindThroughMethodMissing
+
+                def to_coordination_task(task_model = Roby::Task)
+                    self
+                end
+
+                # This method must be overloaded in the tasks that will be
+                # actually used in the coordination primitives
+                def instanciate(plan, variables = Hash.new)
+                    raise NotImplementedError, "must reimplement #instanciate in the task objects used in coordination primitives"
+                end
+
+                def setup_instanciated_task(coordination_context, task, arguments = Hash.new)
+                end
+            end
+        end
+    end
+end
+