roby 0.7.3 → 0.8.0

data/lib/roby/planning/task.rb

@@ -1,34 +1,50 @@
-require 'roby/task'
-require 'roby/relations/planned_by'
-require 'roby/control'
-require 'roby/transactions'
-
 module Roby
     # An asynchronous planning task using Ruby threads
     class PlanningTask < Roby::Task
 	attr_reader :planner, :transaction
 
-	arguments :planner_model, :method_name, 
-	    :method_options, :planned_model, 
-	    :planning_owners
+	arguments :planner_model, :method_options, :method_name, :planned_model, :planning_owners
+
+        def planning_method
+            arguments[:planning_method]
+        end
+
+        def self.validate_planning_options(options)
+            options = options.dup
+            if options[:method_name]
+                method_name = options[:planning_method] = options[:method_name]
+            elsif options[:planning_method].respond_to?(:to_str) || options[:planning_method].respond_to?(:to_sym)
+                method_name = options[:method_name] = options[:planning_method].to_s
+            end
+
+	    if !options[:planner_model]
+		raise ArgumentError, "missing required argument 'planner_model'"
+	    elsif !options[:planning_method]
+		raise ArgumentError, "missing required argument 'planning_method'"
+            elsif !method_name
+                if options[:planning_method].kind_of?(Roby::Planning::MethodDefinition)
+                    method_name = options[:method_name] = options[:planning_method].name
+                else
+                    raise ArgumentError, "the planning_method argument is neither a method object nor a name"
+                end
+	    end
+	    options[:planned_model] ||= nil
+	    options[:planning_owners] ||= nil
+            options
+        end
 
 	def self.filter_options(options)
 	    task_options, method_options = Kernel.filter_options options,
 		:planner_model => nil,
-		:method_name => nil,
+		:planning_method => nil,
 		:method_options => {},
+                :method_name => nil, # kept for backward compatibility
 		:planned_model => nil,
 		:planning_owners => nil
 
-	    if !task_options[:planner_model]
-		raise ArgumentError, "missing required argument 'planner_model'"
-	    elsif !task_options[:method_name]
-		raise ArgumentError, "missing required argument 'method_name'"
-	    end
-	    task_options[:planned_model] ||= nil
+            task_options = validate_planning_options(task_options)
 	    task_options[:method_options] ||= Hash.new
 	    task_options[:method_options].merge! method_options
-	    task_options[:planning_owners] ||= nil
 	    task_options
 	end
 
@@ -38,12 +54,18 @@ module Roby
         end
 
 	def planned_model
-	    arguments[:planned_model] ||= planner_model.model_of(method_name, method_options).returns || Roby::Task
+	    arguments[:planned_model] ||= if method_name
+                                              planner_model.model_of(method_name, method_options).returns
+                                          else
+                                              planning_method.returns
+                                          end
+
+            arguments[:planned_model] ||= Roby::Task
 	end
 
 
 	def to_s
-	    "#{super}[#{method_name}:#{method_options}] -> #{@planned_task || "nil"}"
+	    "#{super}[#{planning_method}:#{method_options}] -> #{@planned_task || "nil"}"
 	end
 
 	def planned_task
@@ -88,7 +110,11 @@ module Roby
         end
 
 	def planning_thread(context)
-	    result_task = planner.send(method_name, method_options.merge(:context => context))
+	    result_task = if planning_method.kind_of?(Roby::Planning::MethodDefinition)
+                              planner.send(:call_planning_methods, Hash.new, method_options.merge(:context => context), planning_method)
+                          else
+                              planner.send(method_name, method_options.merge(:context => context))
+                          end
 
 	    # Don't replace the planning task with ourselves if the
 	    # transaction specifies another planning task
@@ -118,7 +144,7 @@ module Roby
 
 	    # Check if the transaction has been committed. If it is not the
 	    # case, assume that the thread failed
-	    if transaction.freezed?
+	    if transaction.committed?
 		emit :success
 	    else
 		error = begin
@@ -145,6 +171,7 @@ module Roby
 	class TransactionProxy < Roby::Transactions::Task
 	    proxy_for PlanningTask
 	    def_delegator :@__getobj__, :planner
+	    def_delegator :@__getobj__, :planning_method
 	    def_delegator :@__getobj__, :method_name
 	    def_delegator :@__getobj__, :method_options
 	end

data/lib/roby/query.rb

@@ -1,12 +1,12 @@
-require 'roby/plan'
-require 'roby/transactions'
-require 'roby/state/information'
-
 module Roby
     class Task
         # Returns a TaskMatcher object
-	def self.match
-	    TaskMatcher.new
+	def self.match(*args)
+	    matcher = TaskMatcher.new
+            if !args.empty?
+                matcher.which_fullfills(*args)
+            end
+            matcher
 	end
     end
 
@@ -29,11 +29,17 @@ module Roby
 	    @improved_information = ValueSet.new
 	    @needed_information   = ValueSet.new
 	    @interruptible	  = nil
+            @parents              = Hash.new { |h, k| h[k] = Array.new }
+            @children             = Hash.new { |h, k| h[k] = Array.new }
 	end
 
 	# Shortcut to set both model and argument 
 	def which_fullfills(model, arguments = nil)
-	    with_model(model).with_model_arguments(arguments || {})
+	    with_model(model)
+            if arguments
+                with_model_arguments(arguments)
+            end
+            self
 	end
 
 	# Find by model
@@ -47,6 +53,11 @@ module Roby
 	    if !model
 		raise ArgumentError, "set model first"
 	    end
+            if model.respond_to?(:to_ary)
+                valid_arguments = model.inject(Set.new) { |args, m| args | m.arguments.to_set }
+            else
+                valid_arguments = model.arguments
+            end
 	    with_arguments(arguments.slice(*model.arguments))
 	    self
 	end
@@ -132,6 +143,53 @@ module Roby
 	match_predicates :executable, :abstract, :partially_instanciated, :fully_instanciated,
 	    :pending, :running, :finished, :success, :failed, :interruptible, :finishing
 
+        # Helper method for #with_child and #with_parent
+        def handle_parent_child_arguments(other_query, relation, relation_options) # :nodoc:
+            if !other_query.kind_of?(TaskMatcher) && !other_query.kind_of?(Task)
+                if relation.kind_of?(Hash)
+                    arguments = relation
+                    relation         = (arguments.delete(:relation) || arguments.delete('relation'))
+                    relation_options = (arguments.delete(:relation_options) || arguments.delete('relation_options'))
+                else
+                    arguments = Hash.new
+                end
+                other_query = TaskMatcher.which_fullfills(other_query, arguments)
+            end
+            return relation, [other_query, relation_options]
+        end
+
+        def with_child(other_query, relation = nil, relation_options = nil)
+            relation, spec = handle_parent_child_arguments(other_query, relation, relation_options)
+            @children[relation] << spec
+            self
+        end
+
+        def with_parent(other_query, relation = nil, relation_options = nil)
+            relation, spec = handle_parent_child_arguments(other_query, relation, relation_options)
+            @parents[relation] << spec
+            self
+        end
+
+        # Helper method for handling parent/child matches in #===
+        def handle_parent_child_match(task, match_spec) # :nodoc:
+            relation, matchers = *match_spec
+            return false if !relation && task.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 = task.relations.any? do |rel|
+                        yield(rel, m, relation_options)
+                    end
+                    return false if !result
+                end
+            end
+            true
+        end
+
         # True if +task+ matches all the criteria defined on this object.
 	def ===(task)
 	    return unless task.kind_of?(Roby::Task)
@@ -142,6 +200,22 @@ module Roby
 		return unless task.arguments.slice(*arguments.keys) == arguments
 	    end
 
+            for parent_spec in @parents
+                result = handle_parent_child_match(task, parent_spec) do |relation, m, relation_options|
+                    task.enum_parent_objects(relation).
+                        any? { |parent| m === parent && (!relation_options || relation_options === parent[task, relation]) }
+                end
+                return false if !result
+            end
+
+            for child_spec in @children
+                result = handle_parent_child_match(task, child_spec) do |relation, m, relation_options|
+                    task.enum_child_objects(relation).
+                        any? { |child| m === child && (!relation_options || relation_options === task[child, relation]) }
+                end
+                return false if !result
+            end
+
 	    for info in improved_information
 		return false if !task.improves?(info)
 	    end
@@ -159,15 +233,19 @@ module Roby
 	    true
 	end
 
-	STATE_PREDICATES = [:pending?, :running?, :finished?, :success?, :failed?].to_value_set
-        
         # Filters the tasks in +initial_set+ by using the information in
         # +task_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 #===
 	def filter(initial_set, task_index)
 	    if model
-		initial_set &= task_index.by_model[model]
+                if model.respond_to?(:to_ary)
+                    for m in model
+                        initial_set &= task_index.by_model[m]
+                    end
+                else
+                    initial_set &= task_index.by_model[model]
+                end
 	    end
 
 	    if !owners.empty?
@@ -180,11 +258,11 @@ module Roby
 		end
 	    end
 
-	    for pred in (predicates & STATE_PREDICATES)
+	    for pred in (predicates & TaskIndex::STATE_PREDICATES)
 		initial_set &= task_index.by_state[pred]
 	    end
 
-	    for pred in (neg_predicates & STATE_PREDICATES)
+	    for pred in (neg_predicates & TaskIndex::STATE_PREDICATES)
 		initial_set -= task_index.by_state[pred]
 	    end
 
@@ -193,7 +271,9 @@ module Roby
 
         # Enumerates all tasks of +plan+ which match this TaskMatcher object
 	def each(plan, &block)
-	    plan.query_each(plan.query_result_set(self), &block)
+            plan.each_task do |t|
+                yield(t) if self === t
+            end
 	    self
 	end
 
@@ -217,15 +297,36 @@ module Roby
     class Query < TaskMatcher
         # The plan this query acts on
 	attr_reader :plan
+        # Search scope for queries on transactions. If equal to :local, the
+        # query will apply only on the scope of the searched transaction,
+        # otherwise it applies on a virtual plan that is the result of the
+        # transaction stack being applied.
+        #
+        # The default is :global.
+        #
+        # See #local_scope and #global_scope
+        attr_reader :scope
 
         # Create a query object on the given plan
 	def initialize(plan)
+            @scope = :global
 	    @plan = plan
 	    super()
 	    @plan_predicates = Array.new
 	    @neg_plan_predicates = Array.new
 	end
 
+        # Changes the scope of this query. See #scope.
+        def local_scope; @scope = :local end
+        # Changes the scope of this query. See #scope.
+        def global_scope; @scope = :global end
+
+        # Changes the plan this query works on
+        def plan=(new_plan)
+            reset
+            @plan = new_plan
+        end
+
         # The set of tasks which match in plan. This is a cached value, so use
         # #reset to actually recompute this set.
 	def result_set
@@ -304,82 +405,6 @@ module Roby
 	include Enumerable
     end
 
-    # TaskIndex objects are used to maintain a set of tasks as classified sets,
-    # speeding up query operations. See Plan#task_index.
-    class TaskIndex
-        # A model => ValueSet map of the tasks for each model
-	attr_reader :by_model
-	# A state => ValueSet map of tasks given their state. The state is
-	# a symbol in [:pending, :starting, :running, :finishing,
-	# :finished]
-	attr_reader :by_state
-	# A peer => ValueSet map of tasks given their owner.
-	attr_reader :by_owner
-	# The set of tasks which have an event which is being repaired
-	attr_reader :repaired_tasks
-
-	def initialize
-	    @by_model = Hash.new { |h, k| h[k] = ValueSet.new }
-	    @by_state = Hash.new
-	    TaskMatcher::STATE_PREDICATES.each do |state_name|
-		by_state[state_name] = ValueSet.new
-	    end
-	    @by_owner = Hash.new
-	    @task_state = Hash.new
-	    @repaired_tasks = ValueSet.new
-	end
-
-        # Add a new task to this index
-	def add(task)
-	    for klass in task.model.ancestors
-		by_model[klass] << task
-	    end
-	    by_state[:pending?] << task
-	    for owner in task.owners
-		add_owner(task, owner)
-	    end
-	end
-
-        # Updates the index to reflect that +new_owner+ now owns +task+
-	def add_owner(task, new_owner)
-	    (by_owner[new_owner] ||= ValueSet.new) << task
-	end
-
-        # Updates the index to reflect that +peer+ no more owns +task+
-	def remove_owner(task, peer)
-	    if set = by_owner[peer]
-		set.delete(task)
-		if set.empty?
-		    by_owner.delete(peer)
-		end
-	    end
-	end
-
-        # Updates the index to reflect a change of state for +task+
-	def set_state(task, new_state)
-	    for state_set in by_state
-		state_set.last.delete(task)
-	    end
-	    by_state[new_state] << task
-	    if new_state == :success? || new_state == :failed?
-		by_state[:finished?] << task
-	    end
-	end
-
-        # Remove all references of +task+ from the index.
-	def remove(task)
-	    for klass in task.model.ancestors
-		by_model[klass].delete(task)
-	    end
-	    for state_set in by_state
-		state_set.last.delete(task)
-	    end
-	    for owner in task.owners
-		remove_owner(task, owner)
-	    end
-	end
-    end
-
     # This task combines multiple task matching predicates through a OR boolean
     # operator.
     class OrTaskMatcher < TaskMatcher
@@ -472,6 +497,15 @@ module Roby
 	    q
 	end
 
+        # Starts a local query on this plan
+        #
+        # See Query#scope
+        def find_local_tasks(*args, &block)
+            query = find_tasks(*args, &block)
+            query.local_scope
+            query
+        end
+
 	# Called by TaskMatcher#result_set and Query#result_set to get the set
 	# of tasks matching +matcher+
 	def query_result_set(matcher)
@@ -563,9 +597,11 @@ module Roby
 	# tasks matching it. The two sets are disjoint.
 	def query_result_set(matcher)
 	    plan_set = ValueSet.new
-	    for task in plan.query_result_set(matcher)
-		plan_set << task unless self[task, false]
-	    end
+            if matcher.scope == :global
+                for task in plan.query_result_set(matcher)
+                    plan_set << task unless self[task, false]
+                end
+            end
 	    
 	    transaction_set = super
 	    [plan_set, transaction_set]

data/lib/roby/relations.rb

@@ -1,13 +1,16 @@
-require 'roby/support'
-require 'roby/graph'
-
 module Roby
     # This exception is raised when an edge is being added in a DAG, while this
     # edge would create a cycle.
     class CycleFoundError < RuntimeError; end
 
-    # Base support for relations. It is mixed-in objects that are part of
-    # relation networks (like Task and EventGenerator)
+    # Base support for relations. It is mixed in objects on which a
+    # RelationSpace applies on, like Task for TaskStructure and EventGenerator
+    # for EventStructure.
+    #
+    # See also the definition of RelationGraph#add_relation and
+    # RelationGraph#remove_relation for the possibility to define hooks that
+    # get called when a new edge involving +self+ as a vertex gets added and
+    # removed 
     module DirectedRelationSupport
 	include BGL::Vertex
 
@@ -19,8 +22,20 @@ module Roby
 	alias :each_relation	    :each_graph
 	alias :clear_relations	    :clear_vertex
 
+        ##
+        # :method: enum_relations => enumerator
+        # Returns an Enumerator object for the set of relations this object is
+        # included in. The same enumerator instance is always returned.
 	cached_enum("graph", "relations", false)
+        ##
+        # :method: enum_parent_objects(relation) => enumerator
+        # Returns an Enumerator object for the set of parents this object has
+        # in +relation+. The same enumerator instance is always returned.
 	cached_enum("parent_object", "parent_objects", true)
+        ##
+        # :method: enum_child_objects(relation) => enumerator
+        # Returns an Enumerator object for the set of children this object has
+        # in +relation+. The same enumerator instance is always returned.
 	cached_enum("child_object", "child_objects", true)
 
 	# The array of relations this object is part of
@@ -65,24 +80,9 @@ module Roby
 	    parent.add_child_object(self, relation, info)
 	end
 
-	# Hook called before a new child is added in the +relation+ relation
-	# def adding_child_object(child, relation, info)
-	#     child.adding_parent_object(self, relations, info)
-	#     super if defined? super
-	# end
-	# Hook called after a new child has been added in the +relation+ relation
-	# def added_child_object(child, relations, info)
-	#     child.added_parent_object(self, relation, info)
-	#     super if defined? super
-	# end
-
-	# Hook called after a new parent has been added in the +relation+ relation
-	#def added_parent_object(parent, relation, info); super if defined? super end
-	## Hook called after a new parent is being added in the +relation+ relation
-	#def adding_parent_object(parent, relation, info); super if defined? super end
-
-	# Remove the relation between +self+ and +child+. If +relation+ is
-	# given, remove only a relations in this relation kind.
+        # Remove all edges in which +self+ is the source and +child+ the
+        # target. If +relation+ is given, it removes only the edge in that
+        # relation graph.
 	def remove_child_object(child, relation = nil)
 	    check_is_relation(relation)
 	    apply_selection(relation, (relation || enum_relations)) do |relation|
@@ -90,8 +90,8 @@ module Roby
 	    end
 	end
 
-	# Remove relations where self is a parent. If +relation+ is given,
-	# remove only the relations in this relation graph.
+        # Remove all edges in which +self+ is the source. If +relation+
+        # is given, it removes only the edges in that relation graph.
 	def remove_children(relation = nil)
 	    apply_selection(relation, (relation || enum_relations)) do |relation|
 		self.each_child_object(relation) do |child|
@@ -100,13 +100,15 @@ module Roby
 	    end
 	end
 
-	# Remove relations where +self+ is a child. If +relation+ is given,
-	# remove only the relations in this relation graph
+        # Remove all edges in which +child+ is the source and +self+ the
+        # target. If +relation+ is given, it removes only the edge in that
+        # relation graph.
 	def remove_parent_object(parent, relation = nil)
 	    parent.remove_child_object(self, relation)
 	end
-	# Remove all parents of +self+. If +relation+ is given, remove only the
-	# parents in this relation graph
+
+        # Remove all edges in which +self+ is the target. If +relation+
+        # is given, it removes only the edges in that relation graph.
 	def remove_parents(relation = nil)
 	    check_is_relation(relation)
 	    apply_selection(relation, (relation || enum_relations)) do |relation|
@@ -116,24 +118,10 @@ module Roby
 	    end
 	end
 
-	# Hook called after a parent has been removed
-	# def removing_parent_object(parent, relation); super if defined? super end
-	# Hook called after a child has been removed
-	# def removing_child_object(child, relation)
-	#     child.removing_parent_object(self, relation)
-	#     super if defined? super
-	# end
-
-	# Hook called after a parent has been removed
-	# def removed_parent_object(parent, relation); super if defined? super end
-	# Hook called after a child has been removed
-	# def removed_child_object(child, relation)
-	#     child.removed_parent_object(self, relation)
-	#     super if defined? super
-	# end
-
 	# Remove all relations that point to or come from +to+ If +to+ is nil,
-	# it removes all relations of +self+
+	# it removes all edges in which +self+ is involved.
+        #
+        # If +relation+ is not nil, only edges of that relation graph are removed.
 	def remove_relations(to = nil, relation = nil)
 	    check_is_relation(relation)
 	    if to
@@ -172,16 +160,28 @@ module Roby
     end
 
     # This class manages the graph defined by an object relation in Roby.
+    # 
     # Relation graphs are managed in hierarchies (for instance, in
     # EventStructure, Precedence is a superset of CausalLink, and CausalLink a
     # superset of both Forwarding and Signal). In this hierarchy, at each
     # level, an edge cannot be present in more than one graph. Nonetheless, it
     # is possible for a parent relation to have an edge which is present in
     # none of its children.
+    #
+    # Each relation define two things:
+    # * a graph, which is represented by the RelationGraph instance itself
+    # * support methods that are defined on the vertices of the relation. They 
+    #   allow to manage the vertex in its relations easily. Those methods are
+    #   defined in a separate module (see #support)
+    #
+    # In general, relations are part of a RelationSpace instance, which manages
+    # the set of relations whose vertices are of the same kind (for instance
+    # TaskStructure manages all relations whose vertices are Task instances).
+    # In these cases, RelationSpace#relation allow to define new relations easily.
     class RelationGraph < BGL::Graph
 	# The relation name
 	attr_reader   :name
-	# The relation parent if any
+	# The relation parent (if any). See #superset_of.
 	attr_accessor :parent
 	# The set of graphs
 	attr_reader   :subsets
@@ -194,17 +194,18 @@ module Roby
         #   if the graph is a DAG. If true, add_relation will check that
 	#   no cycle is created
 	# +subsets+:: 
-        #   a set of RelationGraph objects that are children of this
-	#   one
+        #   a set of RelationGraph objects that are children of this one.
+        #   See #superset_of.
 	# +distributed+:: 
         #   if this relation graph should be seen by remote hosts
 	def initialize(name, options = {})
-	    @name = name
+	    @name    = name
 	    @options = options
 	    @subsets = ValueSet.new
 	    @distribute = options[:distribute]
-	    @dag = options[:dag]
-	    @weak = options[:weak]
+	    @dag     = options[:dag]
+	    @weak    = options[:weak]
+            @embeds_info = !options[:noinfo]
 
 	    if options[:subsets]
 		options[:subsets].each(&method(:superset_of))
@@ -220,17 +221,38 @@ module Roby
         # break cross-relations cycles (cycles which exist in the graph union
         # of all the relation graphs).
 	attr_predicate :weak
+        # If this relation embeds some additional information
+        attr_predicate :embeds_info?
 
 	def to_s; name end
 
 	# True if this relation does not have a parent
 	def root_relation?; !parent end
 
-        # Add a relation between +from+ and +to+. The relation is added on all
-        # parent relation graphs as well.
-	#
-        # If #dag? is true, it checks that the new relation does not create a
-        # cycle
+        # Remove +vertex+ from this graph. It removes all relations that
+        # +vertex+ is part of, and calls the corresponding hooks
+        def remove(vertex)
+            vertex.remove_relations(nil, self)
+            super
+        end
+
+        # Add an edge between +from+ and +to+. The relation is added on all
+        # parent relation graphs as well. If #dag? is true on +self+ or on one
+        # of its parents, the method will raise CycleFoundError in case the new
+        # edge would create a cycle.
+        #
+        # If +from+ or +to+ define the following hooks:
+        #   adding_parent_object(parent, relations, info)
+        #   adding_child_object(child, relations, info)
+        #   added_parent_object(parent, relations, info)
+        #   added_child_object(child, relations, info)
+        #
+        # then these hooks get respectively called before and after having
+        # added the relation, where +relations+ is the set of RelationGraph
+        # instances where the edge has been added. It can be either [+self+] if
+        # the edge does not already exist in it, or [+self+, +parent+,
+        # <tt>parent.parent</tt>, ...] if the parent, grandparent, ... graphs
+        # do not include the edge either.
 	def add_relation(from, to, info = nil)
 	    # Get the toplevel DAG in our relation hierarchy. We only test for the
 	    # DAG property on this one, as it is the union of all its children
@@ -239,37 +261,25 @@ module Roby
 	    rel     = self
 	    while rel
 		top_dag = rel if rel.dag?
-		new_relations << rel
+                if !rel.linked?(from, to)
+                    new_relations << rel
+                end
 		rel = rel.parent
 	    end
 	    if top_dag && !top_dag.linked?(from, to) && top_dag.reachable?(to, from)
 		raise CycleFoundError, "cannot add a #{from} -> #{to} relation since it would create a cycle"
 	    end
 
-	    # Now compute the set of relations in which we really have to add a
-	    # new relation
-	    top_rel = new_relations.last
-	    if top_rel.linked?(from, to)
-		if !(old_info = from[to, top_rel]).nil?
-		    if old_info != info
-			raise ArgumentError, "trying to change edge information"
-		    end
-		end
-
-		changed_info = [new_relations.pop]
-
-		while !new_relations.empty?
-		    if new_relations.last.linked?(from, to)
-			changed_info << new_relations.pop
-		    else
-			break
-		    end
-		end
-
-		for rel in changed_info
-		    from[to, rel] = info
-		end
-	    end
+	    # Now check that we're not changing the edge info. This is ignored
+            # if +self+ has the noinfo flag set.
+            if linked?(from, to)
+                if !(old_info = from[to, self]).nil?
+                    if old_info != info && !(info = merge_info(from, to, old_info, info))
+                        raise ArgumentError, "trying to change edge information in #{self} for #{from} => #{to}: old was #{old_info} and new is #{info}"
+                    end
+                end
+                from[to, self] = info
+            end
 
 	    unless new_relations.empty?
 		if from.respond_to?(:adding_child_object)
@@ -280,7 +290,7 @@ module Roby
 		end
 
 		for rel in new_relations
-		    rel.__bgl_link(from, to, info)
+		    rel.__bgl_link(from, to, (info if self == rel))
 		end
 
 		if from.respond_to?(:added_child_object)
@@ -292,22 +302,43 @@ module Roby
 	    end
 	end
 
+        def merge_info(from, to, old, new)
+        end
+
 	alias :__bgl_link :link
 	# Reimplemented from BGL::Graph. Unlike this implementation, it is
 	# possible to add an already existing edge if the +info+ parameter
 	# matches.
 	def link(from, to, info)
 	    if linked?(from, to)
-		if info != from[to, self]
-		    raise ArgumentError, "trying to change edge information"
+                old_info = from[to, self]
+		if info != old_info
+                    if info = merge_info(from, to, old_info, info)
+                        from[to, self] = info
+                        return
+                    else
+                        raise ArgumentError, "trying to change edge information"
+                    end
 		end
 		return
 	    end
-	    super
+	    super(from, to, info)
 	end
 
-	# Remove the relation between +from+ and +to+, in this graph and in its
-	# parent graphs as well
+        # Remove the relation between +from+ and +to+, in this graph and in its
+        # parent graphs as well.
+        #
+        # If +from+ or +to+ define the following hooks:
+        #   removing_parent_object(parent, relations)
+        #   removing_child_object(child, relations)
+        #   removed_parent_object(parent, relations)
+        #   removed_child_object(child, relations)
+        #
+        # then these hooks get respectively called once before and once after
+        # having removed the relation, where +relations+ is the set of
+        # RelationGraph instances where the edge has been removed. It is always
+        # <tt>[self, parent, parent.parent, ...]</tt> up to the root relation
+        # which is a superset of +self+.
 	def remove_relation(from, to)
 	    rel = self
 	    relations = []
@@ -337,17 +368,31 @@ module Roby
 
 	# Returns true if +relation+ is included in this relation (i.e. it is
 	# either the same relation or one of its children)
+        #
+        # See also #superset_of
 	def subset?(relation)
 	    self.eql?(relation) || subsets.any? { |subrel| subrel.subset?(relation) }
 	end
 
 	# Returns +true+ if there is an edge +source+ -> +target+ in this graph
 	# or in one of its parents
-	def linked_in_hierarchy?(source, target) # :nodoc:
+        #
+        # See #superset_of for a description of the parent mechanism
+	def linked_in_hierarchy?(source, target)
 	    linked?(source, target) || (parent.linked?(source, target) if parent)
 	end
 
-	# Declare that +relation+ is a superset of this relation
+	# Declare that +self+ is a superset of +relation+. Once this is done,
+        # the system manages two constraints:
+        # * all new relations added in +relation+ are also added in +self+
+        # * it is not allowed for an edge to exist in two different subsets of
+        #   +self+
+        # * of course, if +self+ is a DAG, then in effect +relation+ is constrained
+        #   to be one as well.
+        #
+        # One single graph can be the superset of multiple subgraphs (these are
+        # stored in the #subsets attribute), but one graph can have only one
+        # parent (#parent).
 	def superset_of(relation)
 	    relation.each_edge do |source, target, info|
 		if linked_in_hierarchy?(source, target)
@@ -368,27 +413,44 @@ module Roby
 	attr_accessor :support
     end
 
-    # A relation space is a module which handles a list of relations and
-    # applies them to a set of classes. In this context, a relation is both a
-    # Ruby module which gets included in the classes this space is applied on,
-    # and a RelationGraph object which holds the object graphs.
+    # A relation space is a module which handles a list of relations
+    # (RelationGraph instances) and applies them to a set of classes.
+    # For instance, the TaskStructure relation space is defined by
+    #   TaskStructure = RelationSpace(Task)
+    #
+    # See the files in roby/relations to see example definitions of new
+    # relations
+    #
+    # Use RelationSpace#relation allow to define a new relation in a given
+    # space. For instance, one can either do
+    #
+    #   TaskStructure.relation :NewRelation
     #
-    # See the files in roby/relations to see definitions of new relations
+    # or
+    #
+    #   module TaskStructure
+    #       relation :NewRelation
+    #   end
+    #
+    # This relation can then be referenced by
+    # <tt>TaskStructure::NewRelation</tt>
     class RelationSpace < Module
 	# The set of relations included in this relation space
 	attr_reader :relations
-	# The set of klasses on which the relations have been applied
+	# The set of classes on which the relations have been applied
 	attr_reader :applied
 
-	def initialize
+	def initialize # :nodoc:
 	    @relations = Array.new
 	    @applied   = Array.new
 	    super
 	end
 
-        # This relation applies on klass. It mainly means that a relation
+        # This relation applies on +klass+. It mainly means that a relation
         # defined on this RelationSpace will define the relation-access methods
-        # and include its support module (if any) in +klass+.
+        # and include its support module (if any) in +klass+. Note that the
+        # DirectedRelationSupport module is automatically included in +klass+
+        # as well.
 	def apply_on(klass)
 	    klass.include DirectedRelationSupport
 	    each_relation do |graph|
@@ -405,18 +467,20 @@ module Roby
 	    end
 	end
 
-        # Yields the root relations that are defined on this space
+        # Yields the root relations that are defined on this space. A relation
+        # is a root relation when it has no parent relation (i.e. it is the
+        # subset of no other relations).
 	def each_root_relation
 	    for rel in relations
 		yield(rel) unless rel.parent
 	    end
 	end
 
-	# Returns the set of objects that are reachable from +obj+ through any
-	# of the relations. Note that +b+ will be included in the result if
-	# there is an edge <tt>obj => a</tt> in one relation and another edge
-	# <tt>a => b</tt> in another relation
-	#
+        # Returns the set of objects that are reachable from +obj+ in the union
+        # graph of all the relations defined in this space. In other words, it
+        # returns the set of vertices so that it exists a path starting at
+        # +obj+ and ending at +v+ in the union graph of all the relations.
+        # 
 	# If +strict+ is true, +obj+ is not included in the returned set
 	def children_of(obj, strict = true, relations = nil)
 	    set = compute_children_of([obj].to_value_set, relations || self.relations)
@@ -445,40 +509,77 @@ module Roby
 
         # Defines a relation in this relation space. This defines a relation
         # graph, and various iteration methods on the vertices.  If a block is
-        # given, it defines a set of functions which should be defined on the
-        # vertex objects.
+        # given, it defines a set of functions which should additionally be
+        # defined on the vertex objects.
+        #
+        # The valid options are:
 	#
-	# = Options
 	# child_name::
 	#   define a <tt>each_#{child_name}</tt> method to iterate
 	#   on the vertex children. Uses the relation name by default (a Child
 	#   relation would define a <tt>each_child</tt> method)
 	# parent_name::
 	#   define a <tt>each_#{parent_name}</tt> method to iterate
-	#   on the vertex parents.  If none is given, no method is defined
-	# subsets:: a list of subgraphs. See RelationGraph#superset_of
+	#   on the parent vertices. If none is given, no method is defined.
+	# subsets:: a list of subgraphs. See RelationGraph#superset_of [empty set by default]
 	# noinfo::
-	#   if the relation embeds some additional information. If true,
+	#   wether the relation embeds some additional information. If false,
 	#   the child iterator method (<tt>each_#{child_name}</tt>) will yield (child,
-	#   info) instead of only child [false]
-	# graph:: the relation graph class
-	# distribute:: if true, the relation can be seen by remote peers [true]
+	#   info) instead of only child [false by default]
+	# graph:: the relation graph class [RelationGraph by default]
+	# distribute:: if true, the relation can be seen by remote peers [true by default]
 	# single_child::
-	#   if the relations accepts only one child per vertex
-	#   [false]. If this option is set, defines a <tt>#{child_name}</tt>
-	#   method which returns the only child or nil
+        #   if the relations accepts only one child per vertex. If this option
+        #   is set, defines a <tt>#{child_name}</tt> method which returns the
+        #   only child (or nil if there is no child at all) [false by default]
+        # dag::
+        #   if true, CycleFoundError will be raised if a new vertex would
+        #   create a cycle in this relation [true by default]
+        #
+        # For instance,
+        #   relation :Children
+        #
+        # defines an instance of RelationGraph which is a DAG, defining the
+        # following methods on its vertices:
+        #   each_children { |v, info| ... } => graph
+        #   find_children { |v, info| ... } => object or nil
+        #   add_children(v, info = nil) => graph
+        #   remove_children(v) => graph
+        #
+        # and
+        #
+        #   relation :Children, :child_name => :child
+        #
+        # would define
+        #
+        #   each_child { |v, info| ... } => graph
+        #   find_child { |v, info| ... } => object or nil
+        #   add_child(v, info = nil) => graph
+        #   remove_child(v) => graph
+        #
+        # * the DirectedRelationSupport module gets included in the vertex classes at the
+        #   construction of the RelationSpace instance. See #apply_on.
+        # * the <tt>:noinfo</tt> option would then remove the 'info' parameter
+        #   to the various blocks.
+        # * if <tt>:single_child</tt> is set to true, then an additional method is defined:
+        #     child => object or nil
+        # * and finally if the following is used
+        #     relation :Children, :child_name => :child, :parent_name => :parent
+        #   then the following method is additionally defined
+        #     each_parent { |v| ... }
+        #
 	def relation(relation_name, options = {}, &block)
 	    options = validate_options options,
-			:child_name => relation_name.to_s.underscore,
-			:const_name => relation_name,
+			:child_name  => relation_name.to_s.snakecase,
+			:const_name  => relation_name,
 			:parent_name => nil,
-			:subsets => ValueSet.new,
-			:noinfo => false,
-			:graph => RelationGraph,
-			:distribute => true,
-			:dag => true,
+			:subsets     => ValueSet.new,
+			:noinfo      => false,
+			:graph       => RelationGraph,
+			:distribute  => true,
+			:dag         => true,
 			:single_child => false,
-			:weak => false
+			:weak        => false
 
 	    # Check if this relation is already defined. If it is the case, reuse it.
 	    # This is needed mostly by the reloading code
@@ -503,6 +604,10 @@ module Roby
 	    if parent_enumerator = options[:parent_name]
 		mod.class_eval <<-EOD
 		def each_#{parent_enumerator}(&iterator)
+                    if !block_given?
+                        return enum_parent_objects(@@__r_#{relation_name}__)
+                    end
+
 		    self.each_parent_object(@@__r_#{relation_name}__, &iterator)
 		end
 		EOD
@@ -511,6 +616,10 @@ module Roby
 	    if options[:noinfo]
 		mod.class_eval <<-EOD
 		def each_#{options[:child_name]}
+                    if !block_given?
+                        return enum_child_objects(@@__r_#{relation_name}__)
+                    end
+
 		    each_child_object(@@__r_#{relation_name}__) { |child| yield(child) }
 		end
 		def find_#{options[:child_name]}
@@ -522,10 +631,21 @@ module Roby
 		EOD
 	    else
 		mod.class_eval <<-EOD
-		def each_#{options[:child_name]}
-		    each_child_object(@@__r_#{relation_name}__) do |child|
-			yield(child, self[child, @@__r_#{relation_name}__])
-		    end
+                cached_enum("#{options[:child_name]}", "#{options[:child_name]}", true)
+		def each_#{options[:child_name]}(with_info = true)
+                    if !block_given?
+                        return enum_#{options[:child_name]}(with_info)
+                    end
+
+                    if with_info
+                        each_child_object(@@__r_#{relation_name}__) do |child|
+                            yield(child, self[child, @@__r_#{relation_name}__])
+                        end
+                    else
+                        each_child_object(@@__r_#{relation_name}__) do |child|
+                            yield(child)
+                        end
+                    end
 		end
 		def find_#{options[:child_name]}
 		    each_child_object(@@__r_#{relation_name}__) do |child|
@@ -562,6 +682,11 @@ module Roby
 
 	    graph
 	end
+
+        # Remove +rel+ from the set of relations managed in this space
+        def remove_relation(rel)
+            relations.delete(rel)
+        end
     end
 
     # Creates a new relation space which applies on +klass+. If a block is
@@ -572,12 +697,5 @@ module Roby
         relation_space.apply_on klass
         relation_space
     end
-
-    # Requires all Roby relation files (all files in roby/relations/)
-    def self.load_all_relations
-	Dir.glob("#{File.dirname(__FILE__)}/relations/*.rb").each do |file|
-	    require "roby/relations/#{File.basename(file, '.rb')}"
-	end
-    end
 end