roby 0.8.0 → 3.0.0

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

@@ -0,0 +1,64 @@
+module Roby
+    module Coordination
+        module Models
+            # Definition of model-level functionality for action scripts
+            #
+            # Action scripts are sequential representations of action
+            # coordinations. Each step is a script instruction (created with one
+            # of the API calls in {Script}) whose argument is a {Task} object.
+            # The {Task} object represents the actual work that will be done
+            # there
+            #
+            # Action script models are usually created through an action
+            # interface with Interface#action_script. The script
+            # model can then be retrieved using
+            # {Actions::Models::Action#coordination_model}.
+            #
+            # @example creating an action script
+            #   class Main < Roby::Actions::Interface
+            #     action_script 'example_action' do
+            #       # Start moving at 0.1 m/s until we move more than 0.1m
+            #       move_task = task move(speed: 0.1)
+            #       d_monitor = task monitor_movement_threshold(d: 0.1)
+            #       d_monitor.depends_on move_task
+            #       execute d_monitor
+            #
+            #       # Then, once we're done with that, stand still for 20s
+            #       stand_task = task move(speed: 0)
+            #       t_monitor  = task monitor_time_threshold(t: 20) 
+            #       t_monitor.depends_on stand_task
+            #       execute t_monitor
+            #
+            #       # Finally, announce the success
+            #       emit success_event
+            #     end
+            #   end
+            #
+            # @example retrieving a script model from an action
+            #   Main.find_action_by_name('example_action').coordination_model
+            module ActionScript
+                include Models::Actions
+                include Models::Script
+
+                def respond_to_missing?(m, include_private)
+                    if m =~ /(.*)!/
+                        action_interface && action_interface.find_action_by_name(m.to_s)
+                    else super
+                    end
+                end
+
+                def method_missing(m, *args)
+                    if m =~ /(.*)!/
+                        action_name = $1
+                        action = action_interface.find_action_by_name(action_name)
+                        task = task(action.new(*args))
+                        task.name = action_name
+                        execute(task)
+                    else super
+                    end
+                end
+            end
+        end
+    end
+end
+

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

@@ -0,0 +1,224 @@
+module Roby
+    module Coordination
+        module Models
+
+        # Definition of model-level functionality for action state machines
+        #
+        # In an action state machine, each state is represented by a single Roby
+        # task. At the model level, they get represented by a {Task} object, and
+        # more specifically very often by a {TaskFromAction} object. One
+        # important bit to understand is that a given Task object represents
+        # always the same state (i.e. task0 == task1 if task0 and task1
+        # represent the same state). It is for instance possible that task0 !=
+        # task1 even if task0 and task1 are issued by the same action.
+        #
+        # Transitions are stored as ({Task},{Event},{Task}) triplets, specifying
+        # the origin state, the triggering event and the target state.
+        # {Event#task} is often the same than the origin state, but not
+        # always (see below)
+        #
+        # Note that because some states are subclasses of
+        # {TaskWithDependencies}, it is possible that some {Task} objects
+        # are not states, only tasks that are dependencies of other states
+        # created with {TaskWithDependencies#depends_on} or dependencies of
+        # the state machine itself created with {Actions#depends_on}. The events
+        # of these task objects can be used in transitions
+        #
+        # Action state machine models are usually created through an action
+        # interface with Interface#action_state_machine. The state machine
+        # model can then be retrieved using
+        # {Actions::Models::Action#coordination_model}.
+        #
+        # @example creating an action state machine model
+        #   class Main < Roby::Actions::Interface
+        #     action_state_machine 'example_action' do
+        #       move  = state move(speed: 0.1)
+        #       stand = state move(speed: 0)
+        #       # This monitor triggers each time the system moves more than
+        #       # 0.1 meters
+        #       d_monitor = task monitor_movement_threshold(d: 0.1) 
+        #       # This monitor triggers after 20 seconds
+        #       t_monitor = task monitor_time_threshold(t: 20) 
+        #       # Make the distance monitor run in the move state
+        #       move.depends_on d_monitor
+        #       # Make the time monitor run in the stand state
+        #       stand.depends_on t_monitor
+        #       start move
+        #       transition move, d_monitor.success_event, stand
+        #       transition stand, t_monitor.success_event, move
+        #     end
+        #   end
+        #
+        # @example retrieving a state machine model from an action
+        #   Main.find_action_by_name('example_action').coordination_model
+        module ActionStateMachine
+            include Actions
+
+            # The starting state
+            # @return [Task]
+            attr_reader :starting_state
+
+            # The set of defined transitions
+            #
+            # @return [Array<(Task,Event,Task)>]
+            inherited_attribute(:transition, :transitions) { Array.new }
+
+            # (see Actions#toplevel_state?)
+            def toplevel_state?(state)
+                root == state ||
+                    starting_state == state ||
+                    transitions.any? { |from_state, _, to_state| from_state == state || to_state == state }
+            end
+
+            # @see (Base#map_task)
+            def map_tasks(mapping)
+                super
+
+                @starting_state = mapping[starting_state]
+                @transitions = transitions.map do |state, event, new_state|
+                    [mapping[state],
+                     mapping[event.task].find_event(event.symbol),
+                     mapping[new_state]]
+                end
+            end
+
+            def parse_names
+                super(Task => '_state', Capture => "")
+            end
+
+            # Declares the starting state
+            def start(state)
+                parse_names
+                @starting_state = validate_task(state)
+            end
+
+            def state(object, task_model = Roby::Task)
+                task(object, task_model)
+            end
+
+            # Capture the value of an event context
+            #
+            # The value returned by #capture is meant to be used as arguments to
+            # other states. This is a mechanism to pass information from one
+            # state to the next.
+            #
+            # @example determine the current heading and servo on it
+            #   measure_heading = state(self.measure_heading)
+            #   start(measure_heading)
+            #   current_heading = capture(measure_heading.success_event)
+            #   transition measure_heading.success_event, keep_heading(heading: current_heading)
+            #
+            def capture(state, event = nil, &block)
+                if !event
+                    state, event = state.task, state
+                end
+
+                if !toplevel_state?(state)
+                    raise ArgumentError, "#{state} is not a toplevel state, a capture's state must be toplevel"
+                elsif !event_active_in_state?(event, state)
+                    raise ArgumentError, "#{event} is not an event that is active in state #{state}"
+                end
+
+                filter =
+                    if block
+                        lambda(&block)
+                    else
+                        lambda { |event| event.context.first }
+                    end
+
+                capture = Capture.new(filter)
+                captures[capture] = [state, event]
+                capture
+            end
+
+            # Returns the state for the given name, if found, nil otherwise
+            #
+            # @return Roby::Coordination::Models::TaskFromAction
+            def find_state_by_name(name) find_task_by_name("#{name}_state") 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
+
+            # Computes the set of states that are used in the transitions but
+            # are actually not reachable
+            #
+            # @return [Array<Task>]
+            def compute_unreachable_states
+                queue = [starting_state].to_set
+                transitions = self.each_transition.to_a.dup
+
+                done_something = true
+                while done_something
+                    done_something = false
+                    transitions.delete_if do |from, _, to|
+                        if queue.include?(from)
+                            queue << to
+                            done_something = true
+                        end
+                    end
+                end
+
+                transitions.map(&:first).to_set
+            end
+
+            # Overloaded from Actions to validate the state machine definition
+            #
+            # @raise [UnreachableStateUsed] if some transitions are using events
+            #   from states that cannot be reached from the start state
+            def parse(&block)
+                super
+
+                if !starting_state
+                    raise ArgumentError, "no starting state defined"
+                end
+
+                # Validate that all source states in transitions are reachable
+                # from the start state
+                unreachable = compute_unreachable_states
+                if !unreachable.empty?
+                    raise UnreachableStateUsed.new(unreachable), "#{unreachable.size} states are used in transitions but are actually not reachable"
+                end
+            end
+
+            # Declares a transition from a state to a new state, caused by an
+            # event
+            #
+            # @overload transition(state.my_event, new_state)
+            #   declares that once the 'my' event on the given state is emitted,
+            #   we should transition to new_state
+            # @overload transition(state, event, new_state)
+            #   declares that, while in state 'state', transition to 'new_state'
+            #   if the given event is emitted
+            #
+            def transition(*spec)
+                parse_names
+
+                if spec.size == 2
+                    state_event, new_state = *spec
+                    transition(state_event.task, state_event, new_state)
+                elsif spec.size != 3
+                    raise ArgumentError, "expected 2 or 3 arguments, got #{spec.size}"
+                else
+                    state, state_event, new_state = *spec
+                    validate_task(state)
+                    validate_task(new_state)
+                    if !event_active_in_state?(state_event, state)
+                        raise EventNotActiveInState, "cannot transition on #{state_event} while in state #{state} as the event is not active in this state"
+                    end
+                    transitions << [state, state_event, new_state]
+                end
+            end
+
+            def to_s
+                "#{action_interface}.#{name}"
+            end
+        end
+        end
+    end
+end
+
+

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

@@ -0,0 +1,191 @@
+module Roby
+    module Coordination
+        module Models
+        # Metamodel for Coordination::Actions
+        module Actions
+            include Base
+
+            attribute(:captures) { Hash.new }
+
+            # The action interface model this state machine model is defined on
+            # @return [Actions::Models::Interface,Actions::Models::Library]
+            attr_accessor :action_interface
+
+            # Create a new coordination model based on a different action
+            # interface
+            def rebind(action_interface)
+                m = dup
+                m.action_interface = action_interface
+
+                task_mapping = Hash.new
+                task_mapping[root] = root.rebind(m)
+                tasks.each do |task|
+                    task_mapping[task] = task.rebind(m)
+                end
+                m.map_tasks(task_mapping)
+                m
+            end
+
+            # (see Base#map_tasks)
+            def map_tasks(mapping)
+                super
+
+                @forwards = forwards.map do |state, event, target_event|
+                    state = mapping[state]
+                    event = mapping[event.task].find_event(event.symbol)
+                    target_event = mapping[target_event.task].find_event(target_event.symbol)
+                    [state, event, target_event]
+                end
+
+                @dependencies = dependencies.map do |task, role|
+                    [mapping[task], role]
+                end
+
+                @captures = captures.map_value do |capture, (state, event)|
+                    [mapping[state], mapping[event.task].find_event(event.symbol)]
+                end
+            end
+
+            # The set of defined forwards
+            #
+            # @return [Array<(Task,Event,Event)>]
+            inherited_attribute(:forward, :forwards) { Array.new }
+
+            # A set of tasks that should always be active when self is active
+            #
+            # @return [Set<Task>]
+            inherited_attribute(:dependency, :dependencies) { Set.new }
+
+            # A list of variables that allow to capture event contexts
+            inherited_attribute(:capture, :captures) { Hash.new }
+
+            # Creates a new state machine model as a submodel of self
+            #
+            # @param [Model<Coordination::Actions>] submodel the submodel that
+            #   is being setup
+            # @option options [Model<Actions::Interface>] :action_interface the action
+            #   interface model on which this state machine is defined
+            # @option options [Model<Roby::Task>] :root the task model that is
+            #   going to be used as a toplevel task for the state machine
+            def setup_submodel(submodel, action_interface: nil, **super_options)
+                super(submodel, **super_options)
+                submodel.action_interface = action_interface
+                submodel
+            end
+
+            # Declares that the given event on the root task of the state should
+            # be forwarded to an event on this task
+            #
+            # @overload forward(state.my_event, target_event)
+            #   declares that, while in state 'state', forward 'my_event' to the
+            #   given event name on the state machine task
+            # @overload forward(state, event, target_event)
+            #   declares that, while in state 'state', forward 'event' to the
+            #   given event name on the state machine task
+            #
+            def forward(*spec)
+                if spec.size == 2
+                    state_event, target_event = *spec
+                    forward(state_event.task, state_event, target_event)
+                elsif spec.size != 3
+                    raise ArgumentError, "expected 2 or 3 arguments, got #{spec.size}"
+                else
+                    state, event, target_event = *spec
+                    if !toplevel_state?(state)
+                        raise NotToplevelState, "cannot specify #{state} as the state to forward from as it is not a toplevel state"
+                    elsif !event_active_in_state?(event, state)
+                        raise EventNotActiveInState, "cannot forward from #{event} while in state #{state} as the event is not active in this state"
+                    elsif !root_event?(target_event)
+                        raise NotRootEvent, "can only forward to a root event"
+                    end
+
+                    forwards << [state, event, target_event]
+                end
+            end
+
+            # @api private
+            #
+            # Raise if the given state is not a toplevel state
+            def toplevel_state?(state)
+                true
+            end
+
+            # @api private
+            #
+            # Raise if an event is not "active" while in a particular state
+            def event_active_in_state?(event, state)
+                event.task == root ||
+                    required_tasks_for(state).has_key?(event.task)
+            end
+
+            # @api private
+            #
+            # Raises if the event is not an event of the root task
+            def root_event?(event)
+                event.task == root
+            end
+
+            # Adds a toplevel dependency
+            #
+            # This declares that the given task should always run while self is
+            # running
+            #
+            # @param [Task] task
+            # @return [Task] the task itself
+            def depends_on(task, role: nil)
+                task = validate_task(task)
+                dependencies << [task, role]
+                task
+            end
+
+            # Returns the set of actions that should be active when the given
+            # task is active, as a mapping from the {Task} object to the roles
+            # that this object has (as "dependency roles")
+            #
+            # It includes task itself, as task should run when it is active
+            # @return [{Task=>Set<String>}]
+            def required_tasks_for(task)
+                result = Hash.new
+                task.dependencies.each do |action, role|
+                    result[action] ||= Set.new
+                    result[action] << role if role
+                end
+                each_dependency do |action, role|
+                    result[action] ||= Set.new
+                    result[action] << role if role
+                end
+                result[task] ||= Set.new
+                result[task] << 'current_task'
+                result
+            end
+
+            # Helper to build delayed arguments
+            def from(object)
+                Roby::Task.from(object)
+            end
+
+            # Helper to build delayed arguments
+            def from_state(state_object = State)
+                Roby::Task.from_state(state_object)
+            end
+
+            # Evaluates a state machine definition block
+            def parse(&block)
+                class_eval(&block)
+            end
+
+            def respond_to_missing?(m, include_private)
+                (action_interface && action_interface.find_action_by_name(m.to_s)) || super
+            end
+
+            def method_missing(m, *args)
+                if action = action_interface.find_action_by_name(m.to_s)
+                    action.new(*args)
+                else return super
+                end
+            end
+        end
+        end
+    end
+end
+