roby 0.8.0 → 3.0.0

data/lib/roby/relations/task_relation_graph.rb

@@ -0,0 +1,20 @@
+module Roby
+    module Relations
+        # Subclass of Relations::Space for tasks.
+        #
+        # It adds attributes that are specific to tasks
+        class TaskRelationGraph < Relations::Graph
+            extend Models::TaskRelationGraph
+
+            # If true, the tasks that have a parent in this relation will still be
+            # available for scheduling. Otherwise, they won't get scheduled
+            attr_predicate :scheduling?, true
+
+            def initialize(scheduling: self.class.scheduling?, **options)
+                super(**options)
+                @scheduling = scheduling
+            end
+        end
+    end
+end
+

data/lib/roby/robot.rb

@@ -1,53 +1,100 @@
+require 'utilrb/logger'
+
 module Robot
-    class << self
-	attr_accessor :logger
+    def self.log_formatter(severity, time, progname, msg)
+        Roby.app.notify(progname, severity.to_s, msg)
+        Roby.logger.formatter.call(severity, time, progname, msg)
     end
-    extend Logger::Forward
+    extend Logger::Root('Robot', Logger::INFO, &method(:log_formatter))
 
-    def self.prepare_action(name, arguments)
-	# Check if +name+ is a planner method, and in that case
-	# add a planning method for it and plan it
-	planner_model = Roby.app.planners.find do |planner_model|
-	    planner_model.has_method?(name)
-	end
-	if !planner_model
-	    raise ArgumentError, "no such planning method #{name}"
-	end
+    # @deprecated use Roby.app.action_from_model instead
+    def self.action_from_model(model)
+        return Roby.app.action_from_model(model)
+    end
+    
+    # @deprecated use Roby.app.find_action_from_name instead
+    def self.find_action_from_name(name)
+        return Roby.app.find_action_from_name(name)
+    end
 
-	m = planner_model.model_of(name, arguments)
+    # @deprecated use Roby.app.action_from_name instead
+    def self.action_from_name(name)
+        return Roby.app.action_from_name(name)
+    end
 
-	# HACK: m.returns should not be nil, but it sometimes happen
-	returns_model = (m.returns if m && m.returns) || Task
+    # @deprecated use Roby.app.prepare_action instead
+    def self.prepare_action(plan, name, **arguments)
+        if plan != Roby.app.plan
+            raise ArgumentError, "cannot call prepare_action with any other plan than Roby.app.plan"
+        end
+        return Roby.app.prepare_action(name, **arguments)
+    end
 
-	if returns_model.kind_of?(Roby::TaskModelTag)
-	    task = Roby::Task.new
-	    task.extend returns_model
-	else
-	    # Create an abstract task which will be planned
-	    task = returns_model.new
-	end
+    # Implements that one can call
+    #
+    #   Robot.action_name! arg0: value0, arg1: value1
+    #
+    # To inject a given action in Roby.plan. The added action is added as a
+    # mission.
+    #
+    # See also Robot.prepare_action
+    def self.method_missing(name, *args)
+        if name.to_s =~ /!$/
+            name = $`.to_sym
+        else
+            super
+        end
 
-	planner = Roby::PlanningTask.new(:planner_model => planner_model, :method_name => name, :method_options => arguments)
-	task.planned_by planner
-	return task, planner
+        if args.size > 1
+            raise ArgumentError, "wrong number of arguments (#{args.size} for 1) in #{name}!"
+        end
+
+        options = args.first || {}
+        task, planner = Roby.app.prepare_action(name, job_id: Roby::Interface::Job.allocate_job_id, **options)
+        task.plan.add_mission_task(task)
+        return task, planner
     end
 
-    def self.method_missing(name, *args)
-	if name.to_s =~ /!$/
-	    name = $`.to_sym
-	else
-	    super
-	end
+    # Declare the robot type of the robot configuration being loaded
+    #
+    # Place this on top of the robot file in config/robots/
+    def self.robot_type(robot_type)
+        # Declare it first
+        Roby.app.robots.declare_robot_type(Roby.app.robot_name, robot_type)
+        # And then set it up
+        Roby.app.robot(Roby.app.robot_name, robot_type)
+    end
 
-	if args.size > 1
-	    raise ArgumentError, "wrong number of arguments (#{args.size} for 1) in #{name}!"
-	end
+    def self.init(&block)
+        Roby.app.on_init(&block)
+    end
 
-	options = args.first || {}
-	task, planner = Robot.prepare_action(name, options)
-	Roby.plan.add_mission(task)
+    def self.setup(&block)
+        Roby.app.on_setup(&block)
+    end
+
+    def self.requires(&block)
+        Roby.app.on_require(&block)
+    end
+
+    def self.clear_models(&block)
+        Roby.app.on_clear_models(&block)
+    end
+
+    def self.cleanup(&block)
+        Roby.app.on_cleanup(&block)
+    end
+
+    def self.config(&block)
+        Roby.app.on_config(&block)
+    end
+
+    def self.controller(&block)
+        Roby.app.controller(&block)
+    end
 
-	return task, planner
+    def self.actions(&block)
+        Roby.app.actions(&block)
     end
 end
 

data/lib/roby/schedulers/basic.rb

@@ -1,34 +1,164 @@
+require 'roby/schedulers/reporting'
+
 module Roby
+    # The namespace in which Roby's default schedulers are defined
+    #
+    # In Roby, the scheduler is an object that decides which tasks to start at
+    # any given time. There can be only one scheduler, which is set at
+    # initialization time with
+    #
+    #   Roby.scheduler = <scheduler object>.
+    #
+    # For instance
+    #
+    #   Roby.scheduler = Roby::Schedulers::Basic.new
+    #
+    # Then, the scheduler's #initial_events method is called at the
+    # beginning of each execution cycle. This method is supposed to call
+    # whatever event is reasonable to call with respect to the system's
+    # state (i.e. execution situation).
     module Schedulers
-	class Basic
-	    attr_reader :query
+        # The basic schedulers uses the Roby's "core" plan model to decide which
+        # tasks can be started.
+        #
+        # See the documentation of Roby::Schedulers for more information
+        #
+        # The basic scheduler starts the tasks for which:
+        #  * the task is pending, executable and owned by the local robot
+        #  * the start event is root in all event relations (i.e. there is
+        #    neither signals and forwards pointing to it).
+        #  * it is root in the dependency relationship
+        #  * if the +include_children+ option of Basic.new is set to true, it
+        #    may be non-root in the dependency relation, in which case it is
+        #    started if and only if it has at least one parent that is running
+        #    (i.e. children are started after their parents).
+        #
+        class Basic < Reporting
+            # The plan on which the scheduler applies
+            attr_reader :plan
+            # The Roby::Query which is used to get the set of tasks that might
+            # be startable
+            attr_reader :query
+            # If true, the scheduler will start tasks which are non-root in the
+            # dependency relation, if they have parents that are already
+            # running. 
             attr_reader :include_children
-	    def initialize(include_children = false)
+
+            # Create a new Basic schedulers that work on the given plan, and
+            # with the provided +include_children+ option.
+            #
+            # See Basic for a description of the +include_children+ option.
+            #
+            # If +plan+ is set to nil, the scheduler will use Roby.plan
+            def initialize(include_children = false, plan = nil)
+                super()
+
+                @plan = plan || Roby.plan
                 @include_children = include_children
-		@query = Roby.plan.find_tasks.
-		    executable.
-		    pending.
-		    self_owned
-	    end
-	    def initial_events
-		for task in query.reset
-		    if !(task.event(:start).root? && task.event(:start).controlable?)
-                        next
+                @query = self.plan.find_tasks.
+                    executable.
+                    pending.
+                    self_owned
+
+                @can_schedule_cache = Hash.new
+                @enabled = true
+            end
+
+            attr_predicate :enabled?, true
+
+            def can_start?(task)
+                start_event = task.start_event
+                if !start_event.controlable?
+                    report_holdoff "start event not controlable", task
+                    return false
+                end
+
+                if (agent = task.execution_agent) && !agent.ready_event.emitted?
+                    report_holdoff "task's execution agent %2 is not ready", task, agent
+                    return false
+                end
+
+                if !start_event.root?(EventStructure::CausalLink)
+                    report_holdoff "start event not root in the causal link relation", task
+                    return false
+                end
+
+                task.each_relation do |r|
+                    if r.respond_to?(:scheduling?) && !r.scheduling? && !task.root?(r)
+                        report_holdoff "not root in %2, which forbids scheduling", task, r
+                        return false 
                     end
+                end
+                true
+            end
+
+            def can_schedule?(task, time = Time.now, stack = [])
+                if !can_start?(task)
+                    report_holdoff "cannot be started", task
+                    return false
+                end
 
-		    root_task =
-                        if task.root?(TaskStructure::Dependency)
-			    true
-                        else
-			    task.planned_tasks.all? { |t| !t.executable? }
-			end
-
-		    if root_task || (include_children && task.parents.any? { |t| t.running? })
-			task.start!
-		    end
-		end
-	    end
-	end
+                root_task =
+                    if task.root?(TaskStructure::Dependency)
+                        true
+                    else
+                        planned_tasks = task.planned_tasks
+                        !planned_tasks.empty? &&
+                            planned_tasks.all? { |t| !t.executable? }
+                    end
+
+                if root_task
+                    true
+                elsif include_children && task.parents.any? { |t| t.running? }
+                    true
+                elsif include_children
+                    report_holdoff "not root, and has no running parent", task
+                    false
+                else
+                    report_holdoff "not root, and include_children is false", task
+                    false
+                end
+            end
+
+            # Starts all tasks that are eligible. See the documentation of the
+            # Basic class for an in-depth description
+            def initial_events
+                @can_schedule_cache.clear
+                time = Time.now
+
+                not_executable = self.plan.find_tasks.
+                    not_executable.
+                    pending.
+                    self_owned
+
+                not_executable.each do |task|
+                    # Try to figure out why ...
+                    if task.execution_agent && !task.execution_agent.ready?
+                        report_pending_non_executable_task("execution agent not ready (%2)", task, task.execution_agent)
+                    elsif task.partially_instanciated?
+                        report_pending_non_executable_task("partially instanciated", task)
+                    else
+                        report_pending_non_executable_task("not executable", task)
+                    end
+                end
+
+                scheduled_tasks = []
+                for task in query.reset
+                    result =
+                        if @can_schedule_cache.include?(task)
+                            @can_schedule_cache[task]
+                        else @can_schedule_cache[task] = can_schedule?(task, time, [])
+                        end
+
+                    if result
+                        task.start!
+                        report_trigger task.start_event
+                        scheduled_tasks << task
+                    end
+                end
+                scheduled_tasks
+            end
+        end
     end
 end
 

data/lib/roby/schedulers/null.rb

@@ -0,0 +1,20 @@
+require 'roby/schedulers/reporting'
+
+module Roby
+    module Schedulers
+        # A scheduler that does nothing, used by {ExecutionEngine} by default
+        class Null < Reporting
+            attr_predicate :enabled?, true
+
+            attr_reader :plan
+
+            def initialize(plan)
+                @plan = plan
+            end
+
+            def initial_events
+                []
+            end
+        end
+    end
+end

data/lib/roby/schedulers/reporting.rb

@@ -0,0 +1,31 @@
+require 'roby/schedulers/state'
+
+module Roby
+    module Schedulers
+        extend Logger::Hierarchy
+        extend Logger::Forward
+
+        class Reporting
+            def report_pending_non_executable_task(msg, task, *args)
+                Roby::Schedulers.debug { State.format_message_into_string(msg, task, *args) }
+                plan.execution_engine.log(:scheduler_report_pending_non_executable_task, msg, task, *args)
+            end
+
+            def report_trigger(generator)
+                Roby::Schedulers.debug { "called #{generator}" }
+                plan.execution_engine.log(:scheduler_report_trigger, generator)
+            end
+
+            def report_holdoff(msg, task, *args)
+                Roby::Schedulers.debug { State.format_message_into_string(msg, task, *args) }
+                plan.execution_engine.log(:scheduler_report_holdoff, msg, task, *args)
+            end
+
+            def report_action(msg, task, *args)
+                Roby::Schedulers.debug { State.format_message_into_string(msg, task, *args) }
+                plan.execution_engine.log(:scheduler_report_action, msg, task, *args)
+            end
+        end
+    end
+end
+

data/lib/roby/schedulers/state.rb

@@ -0,0 +1,129 @@
+module Roby
+    module Schedulers
+        # Objects representing the reports from a scheduler object
+        #
+        # They are saved in logs, and can also be listened to through
+        # {Interface::Interface}
+        class State
+            # Tasks that are pending in the plan, but are not executable
+            attr_accessor :pending_non_executable_tasks
+            # The list of event generators triggered by the scheduler
+            #
+            # @return [EventGenerator]
+            attr_accessor :called_generators
+            # The list of tasks that have been considered for scheduling, but
+            # could not be scheduled, along with the reason
+            #
+            # @return [{Task=>[String,Array]}] a mapping from the task that was
+            #   not scheduled, to a list of messages and objects. The message
+            #   can contain %N placeholders which will be replaced by the
+            #   corresponding element from the array
+            attr_accessor :non_scheduled_tasks
+            # The list of actions that have been taken by the scheduler
+            #
+            # @return [{Task=>[String,Array]}] a mapping from the task on which
+            #   an action was performed, to a list of messages and objects. The message
+            #   can contain %N placeholders which will be replaced by the
+            #   corresponding element from the array
+            attr_accessor :actions
+
+            def initialize
+                @pending_non_executable_tasks = Set.new
+                @called_generators = Set.new
+                @non_scheduled_tasks = Hash.new { |h, k| h[k] = Set.new }
+                @actions = Hash.new { |h, k| h[k] = Set.new }
+            end
+
+            def report_pending_non_executable_task(msg, task, *args)
+                pending_non_executable_tasks << [msg, task, *args]
+            end
+
+            def report_trigger(generator)
+                called_generators << generator
+            end
+
+            def report_holdoff(msg, task, *args)
+                non_scheduled_tasks[task] << [msg, *args]
+            end
+
+            def report_action(msg, task, *args)
+                actions[task] << [msg, *args]
+            end
+
+            # Add information contained in 'state' to this object
+            def merge!(state)
+                pending_non_executable_tasks.merge(state.pending_non_executable_tasks)
+                called_generators.merge(state.called_generators)
+                non_scheduled_tasks.merge!(state.non_scheduled_tasks) do |task, msg0, msg1|
+                    msg0.merge(msg1)
+                end
+                actions.merge!(state.actions) do |task, msg0, msg1|
+                    msg0.merge(msg1)
+                end
+            end
+
+            def pretty_print(pp)
+                if !pending_non_executable_tasks.empty?
+                    has_text = true
+                    pp.text "Pending non-executable tasks"
+                    pp.nest(2) do
+                        pending_non_executable_tasks.each do |args|
+                            pp.breakable
+                            pp.text self.class.format_message_into_string(*args)
+                        end
+                    end
+                end
+
+                if !non_scheduled_tasks.empty?
+                    pp.breakable if has_text
+                    has_text = true
+                    pp.text "Non scheduled tasks"
+                    pp.nest(2) do
+                        non_scheduled_tasks.each do |task, msgs|
+                            pp.breakable
+                            task.pretty_print(pp)
+                            pp.nest(2) do
+                                msgs.each do |msg, *args|
+                                    pp.breakable
+                                    pp.text self.class.format_message_into_string(msg, task, *args)
+                                end
+                            end
+                        end
+                    end
+                end
+
+                if !actions.empty?
+                    pp.breakable if has_text
+                    has_text = true
+                    pp.text "Actions taken"
+                    pp.nest(2) do
+                        actions.each do |task, msgs|
+                            pp.breakable
+                            task.pretty_print(pp)
+                            pp.nest(2) do
+                                msgs.each do |msg, *args|
+                                    pp.breakable
+                                    pp.text self.class.format_message_into_string(msg, task, *args)
+                                end
+                            end
+                        end
+                    end
+                end
+            end
+
+            # Formats a message stored in {#non_scheduled_tasks} into a plain
+            # string
+            def self.format_message_into_string(msg, *args)
+                args.each_with_index.inject(msg) do |msg, (a, i)|
+                    a = if a.respond_to?(:map)
+                            a.map(&:to_s).join(", ")
+                        else a.to_s
+                        end
+                    msg.gsub "%#{i + 1}", a
+                end
+            end
+        end
+    end
+end
+
+