roby 0.8.0 → 3.0.0

data/lib/roby/queries/localized_error_matcher.rb

@@ -0,0 +1,149 @@
+module Roby
+    module Queries
+        # Object that allows to specify generalized matches on a
+        # Roby::LocalizedError object
+        class LocalizedErrorMatcher < MatcherBase
+            # @return [Class] the exception class that should be matched. It
+            #   must be a subclass of LocalizedError, and is LocalizedError by
+            #   default
+            attr_reader :model
+            # @return [#===] the object that will be used to match the error
+            #   origin
+            attr_reader :failure_point_matcher
+            # @return [#===,nil] match object to validate the exception's
+            #   ExeptionBase#original_exceptions
+            attr_reader :original_exception_model
+
+            def initialize
+                super
+                @model = LocalizedError
+                @failure_point_matcher = Queries.any
+                @original_exception_model = nil
+            end
+
+            # Specifies which subclass of LocalizedError this matcher should
+            # look for
+            # @return self
+            def with_model(model)
+                @model = model
+                self
+            end
+
+            # Specifies that the exception object should have an
+            # original_exception registered of the given model
+            #
+            # Set to nil to allow for no original exception at all
+            def with_original_exception(model)
+                if model.respond_to?(:exception_matcher)
+                    @original_exception_model = model.exception_matcher
+                else
+                    @original_exception_model = model
+                end
+                self
+            end
+
+            # Specifies a match on the error origin
+            #
+            # The resulting match is extended, i.e. a task matcher will match
+            # the origin's task event if the origin itself is an event.
+            #
+            # @return self
+            def with_origin(plan_object_matcher)
+                @failure_point_matcher = plan_object_matcher.match
+                if failure_point_matcher.respond_to?(:generalized?) && !plan_object_matcher.respond_to?(:generalized?)
+                    failure_point_matcher.generalized
+                end
+                self
+            end
+
+            # @return [Boolean] true if the given execution exception object
+            #   matches self, false otherwise
+            def ===(exception)
+                if !(model === exception)
+                    return false
+                end
+
+                if original_exception_model
+                    original_exception = exception.original_exceptions.
+                        find { |e| original_exception_model === e }
+                    if !original_exception
+                        return false
+                    end
+                end
+
+                if !exception.failed_task
+                    if !(failure_point_matcher === exception.failed_generator)
+                        return false
+                    end
+                elsif failure_point_matcher.respond_to?(:task_matcher)
+                    if exception.failed_generator
+                        return false if !(failure_point_matcher === exception.failed_generator)
+                    else return false
+                    end
+                else
+                    return false if !(failure_point_matcher === exception.failed_task)
+                end
+
+                original_exception || true
+            end
+
+            def describe_failed_match(exception)
+                if !(model === exception)
+                    return "exception model #{exception} does not match #{model}"
+                end
+
+                if original_exception_model
+                    original_exception = exception.original_exceptions.
+                        find { |e| original_exception_model === e }
+                    if !original_exception
+                        if exception.original_exceptions.empty?
+                            return "expected one of the original exceptions to match #{original_exception_model}, but none are registered"
+                        else
+                            return "expected one of the original exceptions to match #{original_exception_model}, but got #{exception.original_exceptions.map(&:to_s).join(", ")}"
+                        end
+                    end
+                end
+
+                if !exception.failed_task
+                    if !(failure_point_matcher === exception.failed_generator)
+                        return "failure point #{exception.failed_generator} does not match #{failure_point_matcher}"
+                    end
+                elsif failure_point_matcher.respond_to?(:task_matcher)
+                    if exception.failed_generator
+                        if !(failure_point_matcher === exception.failed_generator)
+                            return "failure point #{exception.failed_generator} does not match #{failure_point_matcher}"
+                        end
+                    else
+                        return "exception reports no failure generator but was expected to"
+                    end
+                elsif !(failure_point_matcher === exception.failed_task)
+                    return "failure point #{exception.failed_task} does not match #{failure_point_matcher}"
+                end
+                nil
+            end
+
+            def to_s
+                description = "#{model}.with_origin(#{failure_point_matcher})"
+                if original_exception_model
+                    description.concat(".with_original_exception(#{original_exception_model})")
+                end
+                description
+            end
+
+            def matches_task?(task)
+                if failure_point_matcher.respond_to?(:task_matcher)
+                    failure_point_matcher.task_matcher == task
+                else failure_point_matcher === task
+                end
+            end
+
+            match_predicate :fatal?
+            
+            def to_execution_exception_matcher
+                Roby::Queries::ExecutionExceptionMatcher.new.with_exception(self)
+            end
+        end
+    end
+end
+
+

data/lib/roby/queries/matcher_base.rb

@@ -0,0 +1,107 @@
+module Roby
+    module Queries
+        class MatcherBase
+            # Returns true if calling #filter with a task set and a relevant
+            # index will return the exact query result or not
+            def indexed_query?; false end
+
+            # Enumerates all tasks of +plan+ which match this TaskMatcher object
+            #
+            # It is O(N). You should prefer use Query which uses the plan's task
+            # indexes, thus leading to O(1) in simple cases.
+            def each(plan)
+                return enum_for(__method__, plan) if !block_given?
+                plan.each_task do |t|
+                    yield(t) if self === t
+                end
+                self
+            end
+
+            # Negates this predicate
+            #
+            # The returned task matcher will yield tasks that are *not* matched by
+            # +self+
+            def negate; NotMatcher.new(self) end
+            # AND-combination of two predicates 
+            #
+            # The returned task matcher will yield tasks that are matched by both
+            # predicates.
+            def &(other); AndMatcher.new(self, other) end
+            # OR-combination of two predicates 
+            #
+            # The returned task matcher will yield tasks that match either one
+            # predicate or the other.
+            def |(other); OrMatcher.new(self, other) end
+
+            # Set of predicates that should be true for the object
+            # @return [Array<Symbol>]
+            attr_reader :predicates
+
+            # Set of predicats that should be false for the object
+            #
+            # The predicates are predicate method names (e.g. 'executable' for #executable?)
+            #
+            # @return [Array<Symbol>]
+            attr_reader :neg_predicates
+
+            class << self
+                def declare_class_methods(*names) # :nodoc:
+                    names.each do |name|
+                    raise "no instance method #{name} on #{self}" unless method_defined?(name)
+                    singleton_class.send(:define_method, name) do |*args|
+                        self.new.send(name, *args)
+                    end
+                end
+                end
+
+                def match_predicate(name)
+                    method_name = name.to_s.gsub(/\?$/, '')
+                    class_eval <<-EOD, __FILE__, __LINE__+1
+                    def #{method_name}
+                        if neg_predicates.include?(:#{name})
+                            raise ArgumentError, "trying to match (#{name} & !#{name})"
+                        end
+                        predicates << :#{name}
+                        self
+                    end
+                    def not_#{method_name}
+                        if predicates.include?(:#{name})
+                            raise ArgumentError, "trying to match (#{name} & !#{name})"
+                        end
+                        neg_predicates << :#{name}
+                        self
+                    end
+                    EOD
+                    declare_class_methods(method_name, "not_#{method_name}")
+                end
+
+                # For each name in +names+, define a #name and a #not_name method.
+                # If the first is called, the matcher will match only tasks whose
+                # #name? method returns true.  If the second is called, the
+                # opposite will be done.
+                def match_predicates(*names)
+                    names.each do |name|
+                        match_predicate(name)
+                    end
+                end
+            end
+
+            # The {#match} method is used to convert any object to the
+            # corresponding Query object. For instance, Models::TaskEvent#match
+            # returns the corresponding TaskEventGeneratorMatcher.
+            #
+            # For matchers, it returns self
+            def match
+                self
+            end
+
+            # Describe a failed match in a human-readable way
+            #
+            # It is meant to help debugging in tests
+            #
+            # @return [nil,String]
+            def describe_failed_match(exception)
+            end
+        end
+    end
+end

data/lib/roby/queries/none.rb

@@ -0,0 +1,27 @@
+module Roby
+    module Queries
+        # Implementation of a singleton object that matches no other object
+        module None
+            # @return [Boolean] match operator, always returns false
+            def self.===(other)
+                false
+            end
+
+            class DRoby
+                def proxy(peer)
+                    Queries.none
+                end
+            end
+            def self.droby_dump(peer)
+                DRoby.new
+            end
+        end
+
+        # @return [None] an object that matches nothing
+        def self.none
+            None
+        end
+    end
+end
+
+

data/lib/roby/queries/not_matcher.rb

@@ -0,0 +1,30 @@
+module Roby
+    module Queries
+
+    # Negate a given task-matching predicate
+    #
+    # This matcher will match if the underlying predicate does not match.
+    class NotMatcher < MatcherBase
+        # Create a new TaskMatcher which matches if and only if +op+ does not
+        def initialize(op)
+            @op = op
+        end
+
+        # Filters as much as non-matching tasks as possible out of +task_set+,
+        # based on the information in +task_index+
+        def filter(initial_set, task_index)
+            # WARNING: the value returned by filter is a SUPERSET of the
+            # possible values for the query. Therefore, the result of
+            # NegateTaskMatcher#filter is NOT
+            #
+            #   initial_set - @op.filter(...)
+            initial_set
+        end
+
+        # True if the task matches at least one of the underlying predicates
+        def ===(task)
+            !(@op === task)
+        end
+    end
+    end
+end

data/lib/roby/queries/op_matcher.rb

@@ -0,0 +1,8 @@
+module Roby
+    module Queries
+        # Base class for matchers that are built as operations over other
+        # matchers (e.g. 'or', 'not')
+        class OpMatcher
+        end
+    end
+end

data/lib/roby/queries/or_matcher.rb

@@ -0,0 +1,30 @@
+module Roby
+    module Queries
+
+    # Combines multiple task matching predicates through a OR boolean operator.
+    # I.e. it will match if any of the underlying predicates match.
+    class OrMatcher < MatcherBase
+        # Create a new OrMatcher object combining the given predicates.
+        def initialize(*ops)
+            @ops = ops 
+        end
+
+        # Overload of TaskMatcher#filter
+        def filter(task_set, task_index)
+            result = Set.new
+            for child in @ops
+                result.merge child.filter(task_set, task_index)
+            end
+            result
+        end
+
+        # Add a new predicate to the combination
+        def <<(op); @ops << op end
+
+        def ===(task)
+            @ops.any? { |op| op === task }
+        end
+    end
+
+    end
+end

data/lib/roby/queries/plan_object_matcher.rb

@@ -0,0 +1,363 @@
+module Roby
+    module Queries
+    # Predicate that matches characteristics on a plan object
+    class PlanObjectMatcher < MatcherBase
+        # @api private
+        #
+        # The actual instance that should match
+        #
+        # @return [nil,Object]
+        attr_reader :instance
+
+        # @api private
+        #
+        # A set of models that should be provided by the object
+        #
+        # @return [Array<Class>]
+        attr_reader :model
+        
+        # @api private
+        #
+        # Set of owners that the object should have
+        #
+        # @return [Array<DRobyID>]
+        attr_reader :owners
+
+        # @api private
+        #
+        # Set of predicates that should be true on the object, and for which
+        # the index maintains a set of objects for which it is true
+        #
+        # @return [Array<Symbol>]
+        attr_reader :indexed_predicates
+       
+        # @api private
+        #
+        # Set of predicates that should be false on the object, and for which
+        # the index maintains a set of objects for which it is true
+        #
+        # @return [Array<Symbol>]
+        attr_reader :indexed_neg_predicates
+
+        # @api private
+        #
+        # Per-relation list of in-edges that the matched object is expected to have
+        #
+        # @return [Hash]
+        attr_reader :parents
+
+        # @api private
+        #
+        # Per relation list of out-edges that the matched object is expected to have
+        #
+        # @return [Hash]
+        attr_reader :children
+
+        # Initializes an empty TaskMatcher object
+        def initialize(instance = nil)
+            @instance             = instance
+            @indexed_query        = !@instance
+            @model                = Array.new
+            @predicates           = Array.new
+            @neg_predicates       = Array.new
+            @indexed_predicates     = Array.new
+            @indexed_neg_predicates = Array.new
+            @owners               = Array.new
+            @parents              = Hash.new
+            @children             = Hash.new
+        end
+
+        # Match an instance explicitely
+        def with_instance(instance)
+            @instance = instance
+            @indexed_query = false
+            self
+        end
+
+        # Filters on ownership
+        #
+        # Matches if the object is owned by the listed peers.
+        #
+        # Use #self_owned to match if it is owned by the local plan manager.
+        def owned_by(*ids)
+            @owners |= ids
+            self
+        end
+
+        # Filters locally-owned tasks
+        #
+        # Matches if the object is owned by the local plan manager.
+        def self_owned
+            predicates << :self_owned?
+            self
+        end
+
+        # Filters out locally-owned tasks
+        #
+        # Matches if the object is owned by the local plan manager.
+        def not_self_owned
+            neg_predicates << :self_owned?
+            self
+        end
+
+        # Filters on the task model
+        #
+        # Will match if the task is an instance of +model+ or one of its
+        # subclasses.
+        def with_model(model)
+            @model = Array(model)
+            self
+        end
+
+        class << self
+            # @api private
+            def match_predicate(name, positive_index = nil, negative_index = nil)
+                method_name = name.to_s.gsub(/\?$/, '')
+                if Index::PREDICATES.include?(name)
+                    indexed_predicate = true
+                    positive_index ||= [["#{name}"], []]
+                    negative_index ||= [[], ["#{name}"]]
+                end
+                positive_index ||= [[], []]
+                negative_index ||= [[], []]
+                class_eval <<-EOD, __FILE__, __LINE__+1
+                def #{method_name}
+                    if neg_predicates.include?(:#{name})
+                        raise ArgumentError, "trying to match (#{name} & !#{name})"
+                    end
+                    #{"@indexed_query = false" if !indexed_predicate}
+                    predicates << :#{name}
+                    #{if !positive_index[0].empty? then ["indexed_predicates", *positive_index[0]].join(" << :") end}
+                    #{if !positive_index[1].empty? then ["indexed_neg_predicates", *positive_index[1]].join(" << :") end}
+                    self
+                end
+                def not_#{method_name}
+                    if predicates.include?(:#{name})
+                        raise ArgumentError, "trying to match (#{name} & !#{name})"
+                    end
+                    #{"@indexed_query = false" if !indexed_predicate}
+                    neg_predicates << :#{name}
+                    #{if !negative_index[0].empty? then ["indexed_predicates", *negative_index[0]].join(" << :") end}
+                    #{if !negative_index[1].empty? then ["indexed_neg_predicates", *negative_index[1]].join(" << :") end}
+                    self
+                end
+                EOD
+                declare_class_methods(method_name, "not_#{method_name}")
+            end
+        end
+
+        ##
+        # :method: executable
+        #
+        # Matches if the object is executable
+        #
+        # See also #not_executable, PlanObject#executable?
+
+        ##
+        # :method: not_executable
+        #
+        # Matches if the object is not executable
+        #
+        # See also #executable, PlanObject#executable?
+
+        match_predicates :executable?
+
+        declare_class_methods :with_model, :owned_by, :self_owned
+
+        # Helper method for #with_child and #with_parent
+        def handle_parent_child_arguments(other_query, relation, relation_options) # :nodoc:
+            return relation, [other_query.match, relation_options]
+        end
+
+        # Filters based on the object's children
+        #
+        # Matches if this object has at least one child which matches +query+.
+        #
+        # If +relation+ is given, then only the children in this relation are
+        # considered. Moreover, relation options can be used to restrict the
+        # search even more.
+        #
+        # Examples:
+        #
+        #   parent.depends_on(child)
+        #   TaskMatcher.new.
+        #       with_child(TaskMatcher.new.pending) === parent # => true
+        #   TaskMatcher.new.
+        #       with_child(TaskMatcher.new.pending, Roby::TaskStructure::Dependency) === parent # => true
+        #   TaskMatcher.new.
+        #       with_child(TaskMatcher.new.pending, Roby::TaskStructure::PlannedBy) === parent # => false
+        #
+        #   TaskMatcher.new.
+        #       with_child(TaskMatcher.new.pending,
+        #                  Roby::TaskStructure::Dependency,
+        #                  roles: ["trajectory_following"]) === parent # => false
+        #   parent.depends_on child, role: "trajectory_following"
+        #   TaskMatcher.new.
+        #       with_child(TaskMatcher.new.pending,
+        #                  Roby::TaskStructure::Dependency,
+        #                  roles: ["trajectory_following"]) === parent # => true
+        #
+        def with_child(other_query, relation = nil, relation_options = nil)
+            relation, spec = handle_parent_child_arguments(other_query, relation, relation_options)
+            (@children[relation] ||= Array.new) << spec
+            @indexed_query = false
+            self
+        end
+
+        # Filters based on the object's parents
+        #
+        # Matches if this object has at least one parent which matches +query+.
+        #
+        # If +relation+ is given, then only the parents in this relation are
+        # considered. Moreover, relation options can be used to restrict the
+        # search even more.
+        #
+        # See examples for #with_child
+        def with_parent(other_query, relation = nil, relation_options = nil)
+            relation, spec = handle_parent_child_arguments(other_query, relation, relation_options)
+            (@parents[relation] ||= Array.new) << spec
+            @indexed_query = false
+            self
+        end
+
+        # Helper method for handling parent/child matches in #===
+        def handle_parent_child_match(object, match_spec) # :nodoc:
+            relation, matchers = *match_spec
+            return false if !relation && object.relations.empty?
+            for match_spec in matchers
+                m, relation_options = *match_spec
+                if relation
+                    if !yield(relation, m, relation_options)
+                        return false 
+                    end
+                else
+                    result = object.relations.any? do |rel|
+                        yield(rel, m, relation_options)
+                    end
+                    return false if !result
+                end
+            end
+            true
+        end
+
+        # Returns true if filtering with this TaskMatcher using #=== is
+        # equivalent to calling #filter() using a Index. This is used to
+        # avoid an explicit O(N) filtering step after filter() has been called
+        def indexed_query?
+            @indexed_query
+        end
+
+        def to_s
+            description = 
+                if instance
+                    instance.to_s
+                elsif model.size == 1
+                    model.first.to_s
+                else
+                    "(#{model.map(&:to_s).join(",")})"
+                end
+            ([description] + predicates.map(&:to_s) + neg_predicates.map { |p| "not_#{p}" }).join(".")
+        end
+
+
+        # Tests whether the given object matches this predicate
+        #
+        # @param [PlanObject] object the object to match
+        # @return [Boolean]
+        def ===(object)
+            if instance
+                return false if object != instance
+            end
+
+            if !model.empty?
+                return unless object.fullfills?(model)
+            end
+
+            for parent_spec in @parents
+                result = handle_parent_child_match(object, parent_spec) do |relation, m, relation_options|
+                    object.each_parent_object(relation).
+                        any? { |parent| m === parent && (!relation_options || relation_options === parent[object, relation]) }
+                end
+                return false if !result
+            end
+
+            for child_spec in @children
+                result = handle_parent_child_match(object, child_spec) do |relation, m, relation_options|
+                    object.each_child_object(relation).
+                        any? { |child| m === child && (!relation_options || relation_options === object[child, relation]) }
+                end
+                return false if !result
+            end
+
+            for pred in predicates
+                return false if !object.send(pred)
+            end
+            for pred in neg_predicates
+                return false if object.send(pred)
+            end
+
+            return false if !owners.empty? && !(object.owners - owners).empty?
+            true
+        end
+
+        # @api private
+        #
+        # Resolve the indexed sets needed to filter an initial set in {#filter}
+        #
+        # @return [(Set,Set)] the positive (intersection) and
+        #   negative (difference) sets
+        def indexed_sets(index)
+            positive_sets = []
+            for m in @model
+                positive_sets << index.by_model[m]
+            end
+
+            for o in @owners
+                if candidates = index.by_owner[o]
+                    positive_sets << candidates
+                else
+                    return [Set.new, Set.new]
+                end
+            end
+
+            for pred in @indexed_predicates
+                positive_sets << index.by_predicate[pred]
+            end
+
+            negative_sets = @indexed_neg_predicates.
+                map { |pred| index.by_predicate[pred] }
+
+            return positive_sets, negative_sets
+        end
+
+        # Filters the tasks in +initial_set+ by using the information in
+        # +index+, and returns the result. The resulting set must
+        # include all tasks in +initial_set+ which match with #===, but can
+        # include tasks which do not match #===
+        #
+        # @param [Set] initial_set
+        # @param [Index] index
+        # @return [Set]
+        def filter(initial_set, index, initial_is_complete: false)
+            positive_sets, negative_sets = indexed_sets(index)
+            positive_sets << initial_set if !initial_is_complete || positive_sets.empty?
+
+            negative = negative_sets.shift || Set.new
+            if negative_sets.size > 1
+                negative = negative.dup
+                negative_sets.each { |set| negative.merge(set) }
+            end
+
+            positive_sets = positive_sets.sort_by(&:size)
+
+            result = Set.new
+            result.compare_by_identity
+            positive_sets.shift.each do |obj|
+                result.add(obj) if !negative.include?(obj) && positive_sets.all? { |set| set.include?(obj) }
+            end
+            return result
+        end
+    end
+    end
+end
+