roby 0.8.0 → 3.0.0

data/lib/roby/coordination/task_base.rb

@@ -0,0 +1,69 @@
+module Roby
+    module Coordination
+            class ResolvingUnboundObject < RuntimeError; end
+
+            # Base functionality for task-like objects in coordination models
+            # (Task, Child)
+            class TaskBase
+                # @return [Base] the underlying execution context
+                attr_reader :execution_context
+                # @return [Coordination::Models::Task]
+                attr_reader :model
+
+                def initialize(execution_context, model)
+                    @execution_context = execution_context
+                    @model = model
+                end
+
+                # Method that must be reimplemented in the task objects actually
+                # used in the coordination primitives
+                def resolve
+                    raise NotImplementedError, "#resolve must be reimplemented in objects meant to be used in the coordination primitives"
+                end
+
+                def find_child(role, child_model = nil)
+                    child_model ||= model.find_child_model(role)
+                    if !child_model
+                        begin
+                            task = self.resolve
+                            if child_task = task.find_child_from_role(role)
+                                child_model = child_task.model
+                            end
+                        rescue ResolvingUnboundObject
+                        end
+                    end
+
+                    if child = model.find_child(role, child_model)
+                        execution_context.instance_for(child)
+                    end
+                end
+
+                def find_event(symbol)
+                    if event = model.find_event(symbol)
+                        execution_context.instance_for(event)
+                    end
+                end
+
+                def find_through_method_missing(m, args)
+                    MetaRuby::DSLs.find_through_method_missing(
+                        self, m, args,
+                        '_child' => :find_child,
+                        '_port'  => :find_port,
+                        '_event' => :find_event) || super
+                end
+                def has_through_method_missing?(m)
+                    MetaRuby::DSLs.has_through_method_missing?(
+                        self, m,
+                        '_child' => :has_child?,
+                        '_port'  => :has_port?,
+                        '_event' => :has_event?) || super
+                end
+
+                include MetaRuby::DSLs::FindThroughMethodMissing
+
+                def to_coordination_task(task_model); model.to_coordination_task(task_model) end
+            end
+    end
+end
+
+

data/lib/roby/coordination/task_script.rb

@@ -0,0 +1,293 @@
+module Roby
+    module Coordination
+        extend Logger::Forward
+        extend Logger::Hierarchy
+
+        # Implementation of a task script
+        #
+        # The model-level accessors and API is described in {Models::Script}
+        class TaskScript < Base
+            extend Models::Script
+            include Script
+
+            attr_reader :definition_block
+
+            # @deprecated
+            #
+            # Use #root_task instead
+            def task
+                root_task
+            end
+
+            def parse(&block)
+                @definition_block = block
+                instance_eval(&block)
+            end
+
+            def bind(task)
+                result_model = self.class.superclass.new_submodel(root: model.root.model)
+                result = result_model.new(task)
+                result.parse(&definition_block)
+                result.prepare
+                result
+            end
+
+            def resolve_instructions
+                super
+                model.each_task do |model_task|
+                    script_task = instance_for(model_task)
+                    if script_task.respond_to?(:task) && !script_task.task # Not bound ? Check if the model can be instanciated
+                        task = model_task.instanciate(root_task.plan)
+                        bind_coordination_task_to_instance(script_task, task, on_replace: :copy)
+
+                        # Protect from scheduling until the start is executed
+                        #
+                        # #start_task will be called by the Start instruction
+                        root_task.start_event.add_causal_link(task.start_event)
+                    end
+                end
+                # Now, make the dependencies based on what we do / wait for with
+                # the tasks. Namely, we look at Start (dependency options) and
+                # Wait (success events)
+                instructions.each do |ins|
+                    case ins
+                    when Coordination::Models::Script::Start
+                        task = ins.task.resolve
+                        root_task.depends_on task, ins.dependency_options
+                    end
+                end
+            end
+
+            # Resolve the given event object into a Coordination::Task and a
+            # Coordination::Models::Task
+            def resolve_task(task)
+                if root_task && task.kind_of?(Roby::Task)
+                    root_task.plan.add(task)
+                    model_task = Coordination::Models::Task.new(task.model)
+                    script_task = instance_for(model_task)
+                    bind_coordination_task_to_instance(script_task, task, on_replace: :copy)
+                else
+                    model_task = self.model.task(task)
+                    script_task = instance_for(model_task)
+                end
+
+                return script_task, model_task
+            end
+
+            # Resolve the given event object into a Coordination::Event and a
+            # Coordination::Models::Event
+            def resolve_event(event)
+                if event.respond_to?(:to_sym)
+                    symbol = event
+                    if root_task
+                        event = root_task.find_event(symbol)
+                    else
+                        event = model.root.find_event(symbol)
+                    end
+                    if !event
+                        raise ArgumentError, "#{model.root} has no event called #{symbol}"
+                    end
+                end
+                script_task, model_task = resolve_task(event.task)
+                model_event  = model_task.find_event(event.symbol)
+                script_event = instance_for(model_event)
+                return script_event, model_event
+            end
+
+            # Start the given task at that point in the script, and wait for it
+            # to emit its start event
+            #
+            # @param [Task] task the task that should be started
+            # @param [Hash] dependency_options options that should be passed to
+            #   TaskStructure::Dependency::Extension#depends_on
+            def start(task, explicit_start: false, **dependency_options)
+                task, model_task = resolve_task(task)
+                model.start(model_task, explicit_start: explicit_start, **dependency_options)
+                task
+            end
+
+            # @overload execute(task)
+            #   Deploy and start the given task, and wait for it to finish
+            #   successfully
+            #
+            # @overload execute { ... }
+            #   Execute the content of the given block once
+            def execute(task = nil, &block)
+                if task
+                    task, model_task = resolve_task(task)
+                    model.execute(model_task)
+                    task
+                else
+                    model.instructions << BlockExecute.new(block)
+                    nil
+                end
+            end
+
+            # Wait for an event to be emitted
+            #
+            # @param [Hash] options
+            # @option options [Time,nil] after (nil) if set, only event
+            #   emissions that happened after this value will make the script
+            #   pass this instruction. The default of nil means "from the point
+            #   of this instruction on"
+            #
+            # @example wait first_child.start_event
+            #   Waits until start event has been emitted. Will wait forever if
+            #   the start event has already been emitted
+            # @example wait first_child.start_event, after: Time.at(0)
+            #   Waits for start event to be emitted. Will return immediately if
+            #   it has already been emitted.
+            def wait(event, options = Hash.new)
+                event, model_event = resolve_event(event)
+                model.wait(model_event, options)
+                event
+            end
+
+            # @deprecated
+            #
+            # Use wait(event after: Time.at(0)) instead
+            def wait_any(event, options = Hash.new)
+                wait(event, options.merge(after: Time.at(0)))
+            end
+
+            # Sleep for a given number of seconds
+            #
+            # @param [Float] seconds the number of seconds to stop the script
+            #   execution
+            def sleep(seconds)
+                task = start(Tasks::Timeout.new(delay: seconds), explicit_start: true)
+                wait task.stop_event
+            end
+
+            # Emit the given event
+            def emit(event)
+                event, model_event = resolve_event(event)
+                model.emit(model_event)
+                event
+            end
+
+            # Executes the provided block once per execution cycle
+            #
+            # Call {#transition!} to quit the block
+            def poll(&block)
+                poll_until(poll_transition_event, &block)
+            end
+
+            # Execute the provided block once per execution cycle, until the
+            # given event is emitted
+            def poll_until(event, &block)
+                event, model_event = resolve_event(event)
+                model.instructions << Script::Models::PollUntil.new(model_event, block)
+                event
+            end
+
+            # Quit a {#poll} block
+            def transition!
+                root_task.poll_transition_event.emit
+            end
+
+            # Execute the script instructions given as block. If they take more
+            # than the specified number of seconds, either generate an error or
+            # emit an event (and quit the block)
+            #
+            # @param [Hash] options
+            # @option options [Event] :event (nil) if set, the given event will
+            #   be emitted when the timeout is reached. Otherwise, a
+            #   Script::TimedOut exception is generated with the script's
+            #   supporting task as origin
+            def timeout(seconds, options = Hash.new, &block)
+                timeout = timeout_start(seconds, options)
+                parse(&block)
+                timeout_stop(timeout)
+            end
+
+            # Start a timeout operation. Usually not used directly
+            #
+            # @see timeout
+            def timeout_start(seconds, options = Hash.new)
+                options, timeout_options  = Kernel.filter_options options, emit: nil
+                if event = options[:emit]
+                    script_event, model_event = resolve_event(event)
+                end
+                model.timeout_start(seconds, timeout_options.merge(emit: model_event))
+            end
+
+            # Stop a timeout operation. Usually not used directly
+            #
+            # @see timeout
+            def timeout_stop(timeout)
+                model.timeout_stop(timeout)
+            end
+
+            # Used by Script
+            def start_task(task, explicit_start: false)
+                root_task.start_event.remove_causal_link(task.resolve.start_event)
+                if explicit_start
+                    task.resolve.start_event.call
+                end
+            end
+
+            def respond_to_missing?(m, include_private)
+                if m =~ /_(?:event|child)$/
+                    instance_for(model.root).respond_to?(m)
+                else super
+                end
+            end
+
+            def method_missing(m, *args, &block)
+                if m =~ /_(?:event|child)$/
+                    instance_for(model.root).send(m, *args, &block)
+                else super
+                end
+            end
+        end
+    end
+
+    class Task
+        Models::Task.inherited_attribute(:script, :scripts) { Array.new }
+
+        event :poll_transition
+
+        def self.create_script(*task, &block)
+            script_model = Coordination::TaskScript.new_submodel(root: self)
+            script = script_model.new(*task)
+            if block_given?
+                script.parse(&block)
+            end
+            script
+        end
+
+        # Adds a script that is going to be executed for every instance of this
+        # task model
+        def self.script(&block)
+            s = create_script(&block)
+            scripts << s
+            s
+        end
+
+        on :start do |event|
+            model.each_script do |s|
+                s = s.bind(self)
+                s.step
+            end
+        end
+
+        # Adds a task script that is going to be executed while this task
+        # instance runs.
+        def script(options = Hash.new, &block)
+            execute do |task|
+                script = model.create_script(task, &block)
+                script.prepare
+                script.step
+            end
+            model.create_script(self, &block)
+        end
+
+        def transition!
+            poll_transition_event.emit
+        end
+    end
+end
+
+
+

data/lib/roby/coordination/task_state_machine.rb

@@ -0,0 +1,308 @@
+require 'state_machine/machine'
+
+module Roby
+    # Helper to get a more roby-like feeling to the state machine definitions
+    class StateMachineDefinitionContext
+        attr_reader :task_model
+        attr_reader :state_machine
+
+        def initialize(task_model, state_machine)
+            @task_model = task_model
+            @state_machine = state_machine
+        end
+
+        def script_in_state(state, &block)
+            script_engine = task_model.create_script(&block)
+
+            state_machine.before_transition state_machine.any => state, do: lambda { |proxy|
+                proxy.instance_variable_set :@script_engine, nil
+            }
+            state_machine.state(state) do
+                define_method(:poll) do |task|
+                    if !@script_engine
+                        @script_engine = script_engine.bind(task)
+                        @script_engine.prepare
+                        @script_engine.step
+                    end
+                end
+            end
+        end
+
+        def poll_in_state(state, &block)
+            state_machine.state(state) do
+                define_method(:poll, &block)
+            end
+        end
+
+        def on(event, &block)
+            state_machine.event(event, &block)
+        end
+
+        def respond_to_missing?(m, include_private)
+            state_machine.respond_to?(m)
+        end
+
+        def method_missing(m, *args, &block)
+            state_machine.public_send(m, *args, &block)
+        end
+    end
+
+    # The state machine that can be associate with a task
+    # 
+    class TaskStateMachine
+        # The proxy object class the state machine is working on
+        attr_accessor :proxy
+
+        # Underlying state machine
+        attr_accessor :machine
+
+        # Existing transitions
+        # Transition comes with methods: event, from_name, to_name
+        attr_reader :transitions
+
+        # All state of the state machine
+        attr_reader :states
+
+        def initialize(machine)
+            # Required to initialize underlying state_machine
+            super()
+
+            @proxy       = machine.owner_class.new
+            @machine     = machine
+
+            update
+        end
+
+        def update
+            @states = []
+
+            # introspect to retrieve all transactions of the statemachine
+            @transitions = []
+            collection = @machine.states
+            collection.each do |s_o|
+                collection.each do |s_i|
+                    # status_transitions is added to TaskStateMachine using meta programming
+                    transitions = proxy.status_transitions(from: s_o.name.to_sym, to: s_i.name.to_sym)
+                    @transitions << transitions
+                end
+                @transitions.flatten!
+            end
+
+            # Infer all available states from existing transitions
+            @transitions.each do |t|
+                @states << t.from_name unless @states.index(t.from_name)
+                @states << t.to_name unless @states.index(t.to_name)
+            end
+        end
+
+        def initialize_copy(other)
+            other.name = name 
+            other.proxy = name.new
+            other.machine = machine.dup
+            other.update
+        end
+
+        def respond_to_missing?(m, include_private)
+            proxy.respond_to?(m) || super
+        end
+
+        def method_missing(m, *args, &block)
+            # If proxy provides missing method, then use the proxy
+            if proxy.respond_to?(m)
+                proxy.public_send(m, *args, &block)
+            else
+                # otherwise pass it on
+                super
+            end
+        end
+
+        # Define general poll handler
+        def do_poll(task)
+            begin 
+                proxy.poll(task)
+            rescue NoMethodError => e
+                # poll only if the state has a poll handler defined
+            end
+        end
+
+        # Identifies the current state given a list of subsequent events
+        # Provides a list with the most recent event being last in the list
+        # 
+        def identify_state(event_list)
+            # initalize with all transitions possible
+            paths = {}
+            @transitions.each do |transition|
+                paths[transition] = []
+            end
+
+            paths = []
+            new_paths = []
+            initialized = false
+
+            while event_list.size > 0 
+                current_event = event_list.first
+                # expand path
+                @transitions.each do |transition|
+                    # Get transitions that match event
+                    if current_event == transition.event()
+                        # expand first set of transactions
+                        if not initialized
+                            new_paths << [ transition ]
+                        else
+                            # find transitions that lead to the last transition
+                            paths.each do |path|
+                                if path.last.from_name == transition.to_name
+                                    path << transition
+                                    new_paths << path 
+                                end
+                            end
+                        end
+                    end
+                end
+                paths = new_paths
+                new_paths = []
+                initialized = true
+                event_list.delete_at(0)
+            end
+
+            if paths.size == 1
+                # Retrieve last (by time) transitions target state
+                return paths[0].last.to_name
+            elsif paths.size > 0
+                throw "Event list is ambigious, requiring more events"
+            end
+
+            throw "Event list is invalid"
+        end
+    end # module TaskStateHelper
+
+    # The TaskStateHelper allows to add a statemachine to 
+    # a Roby::Task and allows the tracking of events within
+    # the 'running' state
+    module TaskStateHelper
+        # The default namespace that is added to statemachine methods, e.g. 
+        # when action for transitions are defined
+        def namespace
+            @namespace ||= nil 
+        end
+
+        def namespace=(name)
+            @namespace=name
+        end
+
+        # Proxy object used in the definition of state machines on Roby::Task
+        class Proxy
+            def self.state_machine(*args, &block)
+                StateMachine::Machine.find_or_create(self, *args, &block)
+            end
+        end
+
+        # The state machine model that is running on all tasks of this task
+        # model
+        def state_machine
+            if @state_machine then @state_machine
+            elsif superclass.respond_to?(:state_machine)
+                superclass.state_machine
+            end
+        end
+
+        # Refine the running state of the Roby::Task
+        # using a state machine description. The initial
+        # state of the machine is set to 'running' by default.
+        #
+        # Example: 
+        #     refine_running_state do
+        #         on :pause do
+        #             transition [:running] => paused
+        #         end
+        #         
+        #         on :resume do
+        #             transition [:paused] => :running
+        #         end
+        #         
+        #         state :paused do
+        #             def poll(task)
+        #                 sleep 4
+        #                 task.emit :resume
+        #             end
+        #         end
+        #     end
+        #
+        # Events are translated into roby events 
+        # and the statemachine in hooked into the
+        # on(:yourevent) {|context| ... }
+        # You can add additional event handlers as ususal
+        # using on(:yourevent) .. syntax
+        # 
+        # The current status (substate of the running state)
+        # can be retrieved via 
+        #     yourtask.state_machine.status 
+        # 
+        def refine_running_state (*args, &block)
+            if args.last.kind_of?(Hash) 
+                options = args.pop
+            end
+            options = Kernel.validate_options(options || Hash.new, namespace: nil)
+
+            if options.has_key?(:namespace)
+                self.namespace=options[:namespace]
+            end
+
+            # Check if a model of a class ancestor already exists
+            # If a parent_model exists, prepare the proxy class accordingly
+            # The proxy allows us to use the state_machine library even
+            # with instances 
+            if parent_model = self.superclass.state_machine
+                proxy_model = Class.new(parent_model.owner_class)
+            else
+                proxy_model = Class.new(Proxy)
+            end
+
+            # Create the state machine instance that will serve as base model
+            # for instances of the Roby::Task (or its subclasses) this machine
+            # is associated with The namespace allows to pre/postfix
+            # automatically generated functions, such as for sending events:
+            # <task>.state_machine.pause_<namespace>! or querying the status
+            # <task>.state_machine.<namespace>_paused?  Note cannot use :state
+            # instead of :status here for yet unknown reason Changing the
+            # attribute :status also changes other method definitions, due to
+            # meta programming approach of the underlying library, e.g.
+            # status_transitions(from: ..., to: ...)
+
+            if self.namespace 
+                machine = StateMachine::Machine.find_or_create(proxy_model, :status, initial: :running, namespace: self.namespace)
+            else
+                machine = StateMachine::Machine.find_or_create(proxy_model, :status, initial: :running)
+            end
+
+            machine_loader = StateMachineDefinitionContext.new(self, machine)
+            machine_loader.instance_eval(&block)
+            @state_machine = machine
+
+            import_events_to_roby(machine)
+        end
+
+        def import_events_to_roby(machine)
+            # Roby requires the self to be the subclassed Roby::Task
+            # Thus embed import into refine_running_state and using eval here
+            machine.events.each do |e|
+                if !has_event?(e.name)
+                    event e.name, controlable: true
+                end
+                # when event is called transition the state_machine
+                on(e.name) do |event|
+                    state_machine.send("#{e.name.to_sym}!")
+                end
+            end
+        end
+    end
+
+    class Task
+        extend TaskStateHelper
+        attr_reader :state_machine
+
+        # Setup is done in #initialize
+        # Polling is done in Task.do_poll
+    end
+end # module Roby
+