roby 0.8.0 → 3.0.0

data/lib/roby/schedulers/temporal.rb

@@ -0,0 +1,91 @@
+require 'roby/schedulers/basic'
+module Roby
+    module Schedulers
+        # The temporal scheduler adds to the decisions made by the Basic
+        # scheduler information given by the temporal constraint network.
+        #
+        # See the documentation of Roby::Schedulers for more information
+        class Temporal < Basic
+            # If true, the basic scheduler's constraints must be met for all
+            # tasks. If false, they are applied only on tasks for which no
+            # temporal constraints are set.
+            attr_predicate :basic_constraints?, true
+
+            # The proper graph object that contains the scheduling constraints
+            attr_reader :scheduling_constraints_graph
+
+            def initialize(with_basic = true, with_children = true, plan = nil)
+                super(with_children, plan)
+                @basic_constraints = with_basic
+                @scheduling_constraints_graph = self.plan.
+                    event_relation_graph_for(EventStructure::SchedulingConstraints)
+            end
+
+            def can_schedule?(task, time = Time.now, stack = [])
+                if task.running?
+                    return true
+                elsif !can_start?(task)
+                    report_holdoff "cannot be started", task
+                    return false
+                end
+
+                start_event = task.start_event
+
+                event_filter = lambda do |ev|
+                    if ev.respond_to?(:task)
+                        ev.task != task &&
+                            !stack.include?(ev.task) &&
+                            !scheduling_constraints_graph.related_tasks?(ev.task, task)
+                    else true
+                    end
+                end
+
+                meets_constraints = start_event.meets_temporal_constraints?(time, &event_filter)
+                if !meets_constraints
+                    if failed_temporal = start_event.find_failed_temporal_constraint(time, &event_filter)
+                        report_holdoff "temporal constraints not met (%2: %3)", task, failed_temporal[0], failed_temporal[1]
+                    end
+                    if failed_occurence = start_event.find_failed_occurence_constraint(true, &event_filter)
+                        report_holdoff "occurence constraints not met (%2)", task, failed_occurence
+                    end
+                    return false
+                end
+
+                start_event.each_backward_scheduling_constraint do |parent|
+                    begin
+                        stack.push task
+                        if !can_schedule?(parent.task, time, stack)
+                            report_holdoff "held by a schedule_as constraint with %2", task, parent
+                            return false
+                        end
+                    ensure
+                        stack.pop
+                    end
+                end
+
+                if basic_constraints?
+                    if super
+                        return true
+                    else
+                        # Special case: check in Dependency if there are some
+                        # parents for which a forward constraint from +self+ to
+                        # +parent.start_event+ exists. If it is the case, start
+                        # the task
+                        task.each_parent_task do |parent|
+                            parent.start_event.each_backward_temporal_constraint do |constraint|
+                                if constraint.respond_to?(:task) && constraint.task == task
+                                    Schedulers.debug { "Temporal: #{task} has no running parent, but a constraint from #{constraint} to #{parent}.start exists. Scheduling." }
+                                    return true
+                                end
+                            end
+                        end
+                        return false
+                    end
+                else
+                    return true
+                end
+            end
+        end
+    end
+end
+

data/lib/roby/singletons.rb

@@ -0,0 +1,87 @@
+module Roby
+    @state = Roby::StateSpace.new
+    @conf = Roby::ConfModel.new
+
+    class << self
+        # The one and only Application object
+        def app
+            @app ||= Application.new
+        end
+
+        # The one and only StateSpace object
+        attr_reader :state
+
+        # The one and only ConfModel object
+        attr_reader :conf
+
+        # The main plan
+        #
+        # It is always the same as Roby.app.plan
+        #
+        # @return [Plan]
+        def plan; app.plan end
+
+        # The main execution engine
+        #
+        # It is always the same as Roby.plan.execution_engine
+        #
+        # Note that it is nil until the Roby application is configured
+        #
+        # @return [ExecutionEngine]
+        def execution_engine
+            app.execution_engine
+        end
+
+        # The main scheduler
+        #
+        # It is always the same as Roby.plan.execution_engine.scheduler
+        def scheduler
+            app.plan.execution_engine.scheduler
+        end
+
+        # Sets the main scheduler
+        #
+        # It is always the same as Roby.plan.execution_engine.scheduler
+        def scheduler=(scheduler)
+            app.plan.execution_engine.scheduler = scheduler
+        end
+
+        # The control / policy object
+        #
+        # This is the object that defines the core execution policies (e.g. what
+        # to do if the dependency of a non-running task stops). See
+        # {DecisionControl}
+        def control
+            app.plan.execution_engine.control
+        end
+
+        # Sets the control / policy object
+        #
+        # This is the object that defines the core execution policies (e.g. what
+        # to do if the dependency of a non-running task stops). See
+        # {DecisionControl}
+        def control(object)
+            app.plan.execution_engine.control = object
+        end
+
+        # @deprecated use {Roby.execution_engine} instead
+        def engine
+            Roby.warn_deprecated "Roby.engine is deprecated, use Roby.execution_engine instead"
+            app.execution_engine
+        end
+    end
+    
+    # Defines a global exception handler on the main plan.
+    # See also Plan#on_exception
+    def self.on_exception(matcher, &handler); Roby.app.plan.on_exception(matcher, &handler) end
+
+    # The main state object
+    State = Roby.state
+    # The main configuration object
+    Conf  = Roby.conf
+end
+
+# The main state object
+State = Roby.state
+# The main configuration object
+Conf  = Roby.conf

data/lib/roby/standalone.rb

@@ -1,4 +1,6 @@
 require 'roby'
-Dir.chdir(APP_DIR)
-Roby.app.setup_global_singletons
+if defined? APP_DIR
+    Dir.chdir(APP_DIR)
+end
+Roby.app.base_setup
 

data/lib/roby/standard_errors.rb

@@ -1,49 +1,134 @@
+class Exception
+    # Create a {Queries::CodeErrorMatcher} object that matches this exception
+    #
+    # @return [Queries::CodeErrorMatcher]
+    def self.match
+        Roby::CodeError.match.with_ruby_exception(self)
+    end
+
+    def self.to_execution_exception_matcher
+        match.to_execution_exception_matcher
+    end
+
+    def pretty_print(pp)
+        pp.text "#{message} (#{self.class.name})"
+    end
+    
+    # True if +obj+ is involved in this error
+    def involved_plan_object?(obj)
+        false
+    end
+
+    def user_error?; false end
+end
+
 module Roby
+    # Exception base used for all errors that show an inconsistency inside Roby
+    # itself
+    class InternalError < RuntimeError; end
+
+    # Exception raised if an object is not droby-marshallable in a place where
+    # one is required
+    class NotMarshallable < ArgumentError
+    end
+
+    # Module used to tag exceptions that "wrap" an original error from the user
+    # code
+    #
+    # All such exceptions must give access to the original error by defining an
+    # original_exceptions accessor
+    module UserExceptionWrapper; end
+
+    # Base class for all Roby exceptions
+    class ExceptionBase < RuntimeError
+        # List of Exception objects that caused this
+        #
+        # @return [Array<Exception>]
+        attr_accessor :original_exceptions
+
+        def initialize(exceptions = Array.new)
+            @original_exceptions = exceptions
+        end
+
+        def each_original_exception(&block)
+            @original_exceptions.each(&block)
+        end
+
+        def report_exceptions_from(object)
+            if object.kind_of?(Exception)
+                original_exceptions << object
+            elsif object.respond_to?(:report_exceptions_on)
+                object.report_exceptions_on(self)
+            elsif object.respond_to?(:context) && object.context
+                object.context.each do |c|
+                    report_exceptions_from(c)
+                end
+            elsif object.respond_to?(:failure_reason)
+                report_exceptions_from(object.failure_reason)
+            end
+        end
+    end
+
     # This kind of errors are generated during the plan execution, allowing to
     # blame a fault on a plan object (#failure_point). The precise failure
     # point is categorized in the #failed_event, #failed_generator and
     # #failed_task. It is guaranteed that one of #failed_generator and
     # #failed_task is non-nil.
-    class LocalizedError < RuntimeError
+    class LocalizedError < ExceptionBase
+        # If true, such an exception causes the execution engine to stop tasks
+        # in the hierarchy. Otherwise, it only causes notification(s).
+        def fatal?; true end
+        # If true, such an exception will be propagated in the plan dependency
+        # structure. Otherwise, it's directly reported to the plan itself (which
+        # can choose to handle it).
+        #
+        # This is usually set to false for exceptions that report global
+        # information about the plan, such as e.g. MissionFailedError
+        def propagated?; true end
         # The object describing the point of failure
-	attr_reader :failure_point
+        attr_reader :failure_point
         
         # The objects of the given categories which are related to #failure_point
         attr_reader :failed_event, :failed_generator, :failed_task
 
         # Create a LocalizedError object with the given failure point
         def initialize(failure_point)
-	    @failure_point = failure_point
-	    if failure_point.kind_of?(Event)
-		@failed_event = failure_point
-		@failed_generator = failure_point.generator
-	    elsif failure_point.kind_of?(EventGenerator)
-		@failed_generator = failure_point
-	    elsif failure_point.kind_of?(Task)
-		@failed_task = failure_point
-	    end
-
-	    if !@failed_task && @failed_generator && @failed_generator.respond_to?(:task)
-		@failed_task = failed_generator.task
-	    end
-	    if !@failed_task && !@failed_generator
-		raise ArgumentError, "cannot deduce a task and/or a generator from #{failure_point}"
-	    end
-
-            super("")
-	end
+            super()
+            @failure_point = failure_point
+
+            @failed_task, @failed_event, @failed_generator = nil
+            if failure_point.kind_of?(Event)
+                @failed_event = failure_point
+                @failed_generator = failure_point.generator
+            elsif failure_point.kind_of?(EventGenerator)
+                @failed_generator = failure_point
+            elsif failure_point.kind_of?(Task)
+                @failed_task = failure_point
+            end
+
+            if !@failed_task && @failed_generator && @failed_generator.respond_to?(:task)
+                @failed_task = failed_generator.task
+            end
+            if !@failed_task && !@failed_generator
+                raise ArgumentError, "cannot deduce a task and/or a generator from #{failure_point}"
+            end
+
+            if failed_event
+                failed_event.protect_all_sources
+            end
+        end
+
+        def to_execution_exception
+            ExecutionException.new(self)
+        end
 
         def pretty_print(pp)
-	    pp.text "#{self.class.name}"
+            pp.text "#{self.class.name}"
             if !message.empty?
                 pp.text ": #{message}"
             end
             pp.breakable
             failure_point.pretty_print(pp)
-
-            if backtrace && !backtrace.empty?
-                Roby.pretty_print_backtrace(pp, backtrace)
-            end
         end
 
         # True if +obj+ is involved in this error
@@ -53,17 +138,103 @@ def involved_plan_object?(obj)
                  obj == failed_generator ||
                  obj == failed_task)
         end
+
+        # @return [Queries::ExecutionExceptionMatcher]
+        def self.to_execution_exception_matcher
+            Roby::Queries::ExecutionExceptionMatcher.new.with_model(self)
+        end
+
+        # Create a {Queries::LocalizedErrorMatcher} that matches this exception
+        #
+        # @return [Queries::LocalizedErrorMatcher]
+        def self.match
+            Roby::Queries::LocalizedErrorMatcher.new.with_model(self)
+        end
+    end
+
+    class RelationFailedError < LocalizedError
+        # The parent in the failed relation
+        attr_reader :parent
     end
 
+
+    # Exception raises when attempting to add relations to a
+    # garbaged-but-not-finalized task
+    class ReusingGarbage < RuntimeError; end
+    # Exception class used when trying to perform an operation on a finalized
+    # object and the operation requires a plan
+    class FinalizedPlanObject < RuntimeError; end
     # Raised during event propagation if a task event is called or emitted,
     # while this task is not executable.
     class TaskNotExecutable < LocalizedError; end
     # Raised during event propagation if an event is called or emitted,
     # while this event is not executable.
     class EventNotExecutable < LocalizedError; end
-    # Raised during event propagation if an event is called, while this event
-    # is not controlable.
-    class EventNotControlable < LocalizedError; end
+    # Same error than EventNotExecutable, but for task events
+    #
+    # The only difference is that this method displays some task-specific
+    # information
+    class TaskEventNotExecutable < EventNotExecutable
+        def initialize(failure_point)
+            super(failure_point)
+            if !(@plan = failed_generator.task.plan)
+                @removed_at = failed_generator.task.removed_at
+            end
+        end
+
+        def plan; @plan end
+        def removed_at; @removed_at end
+
+        def pretty_print(pp)
+            pp.text "#{failed_generator.symbol} called but it is not executable on"
+            pp.breakable
+            failed_generator.task.pretty_print(pp)
+            pp.breakable
+            if plan
+                pp.text "the task has NOT been garbage collected"
+            elsif removed_at
+                pp.text "#{failed_generator.task} has been removed from its plan at"
+                removed_at.each do |line|
+                    pp.breakable
+                    pp.text "  #{line}"
+                end
+            else
+                pp.text "the task has never been included in a plan"
+            end
+        end
+    end
+    # Raised when an error occurs on a task while we were terminating it
+    class TaskEmergencyTermination < LocalizedError
+        attr_reader :reason
+
+        def quarantined?
+            !!@quarantined
+        end
+
+        def initialize(task, reason, quarantined = false)
+            super(task)
+
+            @quarantined = quarantined
+            @reason = reason
+            report_exceptions_from(reason)
+        end
+
+        def pretty_print(pp)
+            pp.text "The following task is being terminated because of an internal error"
+            pp.breakable
+            if quarantined?
+                pp.text "It has been put under quarantine"
+            else
+                pp.text "It is not yet put under quarantine"
+            end
+            pp.breakable
+            super
+            pp.breakable
+            if !original_exceptions.include?(reason)
+                reason.pretty_print(pp)
+            end
+        end
+    end
 
     # Raised when an operation is attempted while the ownership does not allow
     # it.
@@ -89,33 +260,54 @@ class ThreadMismatch < RuntimeError; end
     # outside of Roby's plan management algorithms) has raised. This includes:
     # event commands, event handlers, task polling blocks, ...
     class CodeError < LocalizedError
+        include UserExceptionWrapper
+
         # The original exception object
-	attr_reader :error
+        def original_exception; original_exceptions.first end
+        # @deprecated use {#original_exception} instead
+        def error; original_exception end
         # Create a CodeError object from the given original exception object, and
         # with the given failure point
-	def initialize(error, *args)
-	    if error && !error.kind_of?(Exception)
-		raise TypeError, "#{error} should be an exception"
-	    end
-	    super(*args)
-	    @error = error
-	end
-
-	def pretty_print(pp) # :nodoc:
-	    if error
-                pp.text "#{self.class.name}: user code raised an exception "
-                failure_point.pretty_print(pp)
-                pp.breakable
-                pp.breakable
-                error.pretty_print(pp)
-	    else
-		super
-	    end
-	end
+        def initialize(error, *args)
+            if error && !error.kind_of?(Exception)
+                raise TypeError, "#{error} should be an exception"
+            end
+            super(*args)
+            report_exceptions_from(error)
+        end
+
+        def pretty_print(pp)
+            pp.text "#{self.class.name}: user code raised an exception "
+            failure_point.pretty_print(pp)
+        end
+
+        # Create a {Queries::CodeErrorMatcher} that matches this exception
+        #
+        # @return [Queries::CodeErrorMatcher]
+        def self.match
+            Roby::Queries::CodeErrorMatcher.new.with_model(self)
+        end
     end
 
+    # Raised when a command is being processed, but it cannot be (e.g. because
+    # of task state)
+    class CommandRejected < LocalizedError; end
+
+    # Raised when an event's emission has being requested, but it cannot be
+    # (e.g. because of task state)
+    class EmissionRejected < LocalizedError; end
+
     # Raised if a command block has raised an exception
-    class CommandFailed < CodeError; end
+    class CommandFailed < CodeError
+        def pretty_print(pp)
+            pp.text "uncaught exception in the command of the "
+            failed_generator.pretty_print(pp)
+            pp.text " (#{self.class})"
+        end
+    end
+    # Raised during event propagation if an event is called, while this event
+    # is not controlable.
+    class EventNotControlable < LocalizedError; end
     # Raised when the call of an event has been canceled.
     # See EventGenerator#cancel.
     class EventCanceled < LocalizedError; end
@@ -124,17 +316,48 @@ class EventCanceled < LocalizedError; end
     class EventPreconditionFailed < LocalizedError; end
     # Raised when the emission of an event has failed.
     # See EventGenerator#emit_failed.
-    class EmissionFailed < CodeError; end
+    class EmissionFailed < CodeError
+        def initialize(*args, &block)
+            super
+            if !failed_generator
+                raise ArgumentError, "creating an EmissionFailed error without a generator"
+            end
+        end
+
+        def pretty_print(pp) # :nodoc:
+            pp.text "failed emission of the "
+            failed_generator.pretty_print(pp)
+            pp.text " (#{self.class})"
+        end
+    end
     # Raised when an event handler has raised.
-    class EventHandlerError < CodeError; end
+    class EventHandlerError < CodeError
+        def pretty_print(pp)
+            pp.text "uncaught exception in an event handler of the "
+            failed_generator.pretty_print(pp)
+            pp.text " (#{self.class})"
+            pp.breakable
+            pp.text "called during the propagation of "
+            failed_event.pretty_print(pp)
+        end
+    end
 
     # Raised when an exception handler has raised.
     class FailedExceptionHandler < CodeError
-	attr_reader :handled_exception
-	def initialize(error, object, handled_exception)
-	    super(error, object)
-	    @handled_exception = handled_exception
-	end
+        attr_reader :handled_exception
+        attr_reader :handler
+
+        def initialize(error, object, handled_exception, handler)
+            super(error, object)
+            @handled_exception = handled_exception
+            @handler = handler
+        end
+
+        def pretty_print(pp)
+            pp.text "exception handler #{handler} failed while processing"
+            pp.breakable
+            handled_exception.pretty_print(pp)
+        end
     end
 
     # Raised when an event has become unreachable while other parts of the plan
@@ -146,38 +369,31 @@ class UnreachableEvent < LocalizedError
         # Create an UnreachableEvent error for the given +generator+. +reason+
         # is supposed to be either nil or a plan object which is the reason why
         # +generator+ has become unreachable.
-	def initialize(generator, reason)
+        def initialize(generator, reason)
+            super(generator)
             @reason    = reason
-	    super(generator)
-	end
+            report_exceptions_from(reason)
+        end
 
-	def pretty_print(pp) # :nodoc:
+        def pretty_print(pp) # :nodoc:
             pp.text "#{failed_generator} has become unreachable"
-	    if reason
+            if reason
                 reason = [*reason]
                 reason.each do |e|
                     pp.breakable
                     e.pretty_print(pp)
                 end
             end
-	end
+        end
     end
     
     # Exception raised when the event loop aborts because of an unhandled
     # exception
-    class Aborting < RuntimeError
-	attr_reader :all_exceptions
-	def initialize(exceptions)
-            @all_exceptions = exceptions 
-            super("")
-        end
+    class Aborting < ExceptionBase
         def pretty_print(pp) # :nodoc:
             pp.text "control loop aborting because of unhandled exceptions"
-            pp.seplist(",") do
-                all_exceptions.pretty_print(pp)
-            end
         end
-	def backtrace # :nodoc:
+        def backtrace # :nodoc:
             [] 
         end
     end
@@ -185,14 +401,14 @@ def backtrace # :nodoc:
     # Raised by Plan#replace when the new task cannot replace the older one.
     class InvalidReplace < RuntimeError
         # The task being replaced
-	attr_reader :from
+        attr_reader :from
         # The task which should have replaced #from
         attr_reader :to
 
         # Create a new InvalidReplace object
-	def initialize(from, to)
-	    @from, @to = from, to
-	end
+        def initialize(from, to)
+            @from, @to = from, to
+        end
         def pretty_print(pp) # :nodoc:
             pp.text "invalid replacement: #{message}"
             pp.breakable
@@ -205,20 +421,127 @@ def pretty_print(pp) # :nodoc:
     end
     
     # Exception raised when a mission has failed
-    class MissionFailedError < LocalizedError
+    class ToplevelTaskError < LocalizedError
+        include UserExceptionWrapper
+
+        attr_reader :reason
+
+        def propagated?; false end
+
         # Create a new MissionFailedError for the given mission
-	def initialize(task)
-	    super(task.failure_event || task)
-	end
+        def initialize(task, reason = nil)
+            super(task.failure_event || task)
+            @reason = reason || task.failure_reason
+            report_exceptions_from(@reason)
+        end
+
+        def pretty_print(pp)
+            if reason
+                reason.pretty_print(pp)
+            elsif failed_event
+                failed_event.pretty_print(pp)
+            else
+                explanation = :success.to_unbound_task_predicate.explain_static(failed_task)
+                explanation.pretty_print(pp)
+            end
+        end
+    end
 
+    # Exception raised when a mission has failed
+    class MissionFailedError < ToplevelTaskError
         def pretty_print(pp)
             pp.text "mission failed: "
-            super
+            failed_task.pretty_print(pp)
+            pp.breakable
+            super(pp)
+        end
+    end
+
+    # Exception raised when a permanent task has failed
+    class PermanentTaskError < ToplevelTaskError
+        def fatal?; false end
+        def pretty_print(pp)
+            pp.text "permanent task failed: "
+            failed_task.pretty_print(pp)
+            pp.breakable
+            super(pp)
         end
     end
 
     # Exception raised in threads which are waiting for the control thread
     # See for instance Roby.execute
     class ExecutionQuitError < RuntimeError; end
+
+    # Exception raised when a child is being resolved by role, but the role is
+    # not associated with any child
+    class NoSuchChild < ArgumentError
+        # @return [Object] the object whose children we try to access
+        attr_reader :object
+        # @return [String] the role that failed to be resolved
+        attr_reader :role
+        # @return [{String=>Object}] the set of known children
+        attr_reader :known_children
+
+        def initialize(object, role, known_children)
+            @object, @role, @known_children = object, role, known_children
+        end
+
+        def pretty_print(pp)
+            pp.text "#{object} has no child with the role '#{role}'"
+
+            if known_children.empty?
+                pp.text ", actually, it has no child at all"
+            else
+                pp.text ". Known children:"
+                pp.nest(2) do
+                    known_children.each do |role, child|
+                        pp.breakable
+                        pp.text "#{role}: #{child}"
+                    end
+                end
+            end
+        end
+    end
+
+    # Exception raised when a finished task has a promise attached, or when one
+    # attempts to create one on a finished task
+    class PromiseInFinishedTask < RuntimeError; end
+
+    # Exception used when a state transition fails within an action state
+    # machine
+    class ActionStateTransitionFailed < LocalizedError
+        # The state that we're transitioning out of
+        # @return [Coordination::Task]
+        attr_reader :from_state
+        # The event that caused the transition
+        # @return [Event]
+        attr_reader :event
+        # The state that we were transitioning into
+        # @return [Coordination::Task]
+        attr_reader :to_state
+
+        def initialize(root_task, from_state, event, to_state, original_exception)
+            super(root_task)
+            @from_state = from_state
+            @event    = event
+            @to_state = to_state
+            report_exceptions_from(original_exception)
+        end
+
+        def pretty_print(pp)
+            pp.text "#{failed_task} failed a state transition"
+            pp.nest(2) do
+                pp.breakable
+                pp.text "from state "
+                pp.nest(2) { from_state.pretty_print(pp) }
+                pp.breakable
+                pp.text "to state "
+                pp.nest(2) { to_state.pretty_print(pp) }
+                pp.breakable
+                pp.text "caused by event "
+                pp.nest(2) { event.pretty_print(pp) }
+            end
+        end
+    end
 end