roby 0.7

data/lib/roby/relations/conflicts.rb

@@ -0,0 +1,70 @@
+
+module Roby
+    module TaskStructure
+	Roby::Task.inherited_enumerable(:conflicting_model, :conflicting_models) { ValueSet.new }
+	module ModelConflicts
+	    def conflicts_with(model)
+		conflicting_models << model
+		model.conflicting_models << self
+	    end
+
+	    def conflicts_with?(model)
+		each_conflicting_model do |m|
+		    return true if m == model
+		end
+		false
+	    end
+	end
+	Roby::Task.extend ModelConflicts
+
+	relation :Conflicts, :noinfo => true do
+	    def conflicts_with(task)
+		task.event(:stop).add_precedence event(:start)
+		add_conflicts(task)
+	    end
+
+	    def self.included(klass) # :nodoc:
+		klass.extend ModelConflicts
+		super
+	    end
+	end
+    end
+
+    module ConflictEventHandling
+	def calling(context)
+	    super if defined? super
+	    return unless symbol == :start
+
+	    # Check for conflicting tasks
+	    result = nil
+	    task.each_conflicts do |conflicting_task|
+		result ||= ValueSet.new
+		result << conflicting_task
+	    end
+
+	    if result
+		Roby.decision_control.conflict(task, result)
+	    end
+
+	    # Add the needed conflict relations
+	    models = task.class.conflicting_models
+	    for model in models
+		if candidates = plan.task_index.by_model[model]
+		    for t in candidates
+			t.conflicts_with task if t.pending?
+		    end
+		end
+	    end
+	end
+    
+	def fired(event)
+	    super if defined? super
+
+	    if symbol == :stop
+		TaskStructure::Conflicts.remove(task)
+	    end
+	end
+    end
+    Roby::TaskEventGenerator.include ConflictEventHandling
+end
+

data/lib/roby/relations/ensured.rb

@@ -0,0 +1,20 @@
+require 'roby/event'
+module Roby::EventStructure
+    relation :EnsuredEvent, :noinfo => true do
+	def calling(context)
+	    super if defined? super
+	    each_ensured_event do |ev|
+		if !ev.happened?
+		    postpone(ev, "waiting for ensured event #{ev}") do
+			ev.call(context) if ev.controlable?
+		    end
+		end
+	    end
+	end
+
+	def ensure(event)
+	    add_ensured_event event
+	end
+    end
+end
+

data/lib/roby/relations/error_handling.rb

@@ -0,0 +1,23 @@
+
+module Roby::TaskStructure
+    class Roby::TaskEventGenerator
+	# Mark this event as being handled by the task +task+
+	def handle_with(repairing_task)
+	    if !task.child_object?(repairing_task, ErrorHandling)
+		task.add_error_handler repairing_task, ValueSet.new
+	    end
+
+	    task[repairing_task, ErrorHandling] << symbol
+	end
+    end
+
+    relation :ErrorHandling, :child_name => :error_handler do
+	def failed_task
+	    each_parent_object(ErrorHandling) do |task|
+		return task
+	    end
+	    nil
+	end
+    end
+end
+

data/lib/roby/relations/events.rb

@@ -0,0 +1,9 @@
+require 'roby/event'
+
+module Roby::EventStructure
+    relation :Signal, :noinfo => true
+    relation :Forwarding, :noinfo => true
+    relation :CausalLink, :subsets => [Signal, Forwarding], :noinfo => true
+    relation :Precedence, :subsets => [CausalLink], :noinfo => true
+end
+

data/lib/roby/relations/executed_by.rb

@@ -0,0 +1,193 @@
+require 'roby/task'
+
+module Roby::TaskStructure
+    # This module defines model-level definition of execution agent, for
+    # instance to Roby::Task
+    module ModelLevelExecutionAgent
+	# The model of execution agent for this class
+	def execution_agent
+	    for klass in ancestors
+		if klass.instance_variable_defined?(:@execution_agent)
+		    return klass.instance_variable_get(:@execution_agent)
+		end
+	    end
+	    nil
+	end
+
+	# Defines a model of execution agent. Doing
+	#
+	#   TaskModel.executed_by ExecutionAgentModel
+	#
+	# is equivalent to
+	#
+	#   task = TaskModel.new
+	#   exec = <find a suitable ExecutionAgentModel instance in the plan or
+	#	   create a new one>
+	#   task.executed_by exec
+	#   
+	# for all instances of TaskModel. The actual job is done in the
+	# ExecutionAgentSpawn module
+	def executed_by(agent)
+	    @execution_agent = agent
+	end
+    end
+
+    # The execution_agent defines an agent (process or otherwise) a given
+    # task is executed by. It allows to define a class of these execution agent,
+    # so that the specific agents are managed externally (load-balancing, ...)
+    relation :ExecutionAgent, :parent_name => :executed_task, :child_name => :execution_agent, 
+	:noinfo => true, :distribute => false, :single_child => true do
+	
+	# When ExecutionAgent support is included in a model (for instance Roby::Task), add
+	# the model-level classes  
+        def self.included(klass) # :nodoc:
+	    klass.extend Roby::TaskStructure::ModelLevelExecutionAgent
+            super
+        end
+
+	# Defines a new execution agent for this task.
+        def executed_by(agent)
+	    return if execution_agent == agent
+	    if !agent.event(:start).controlable? && !agent.running?
+		raise ArgumentError, "the start event of #{self}'s execution agent #{agent} is not controlable"
+	    end
+	    # Check that agent defines the :ready event
+	    if !agent.has_event?(:ready)
+		raise ArgumentError, "execution agent tasks should define the :ready event"
+	    end
+	    
+	    old_agent = execution_agent
+	    if old_agent && old_agent != agent
+		Roby.debug "an agent is already defined for this task"
+		remove_execution_agent old_agent
+	    end
+
+	    unless old_agent
+		# If the task did have an agent already, these event handlers
+		# are already set up
+		if running?
+		    Roby::Distributed.update(self) do
+			agent.forward(:stop, self, :aborted)
+		    end
+		else
+		    on(:start) do
+			# The event handler will be called even if the
+			# execution agent has been removed. Check that there is
+			# actually an execution agent 
+			if execution_agent
+			    Roby::Distributed.update(self) do
+				execution_agent.forward(:stop, self, :aborted)
+			    end
+			end
+		    end
+		end
+
+		on(:stop) do 
+		    if execution_agent
+			Roby::Distributed.update(self) do
+			    execution_agent.event(:stop).remove_forwarding event(:aborted)
+			    remove_execution_agent execution_agent
+			end
+		    end
+		end
+	    end
+
+	    add_execution_agent(agent)
+        end
+
+    end
+
+    class ExecutionAgentSpawningFailed < Roby::LocalizedError
+	attr_reader :agent_model, :error
+	def initialize(task, agent_model, error)
+	    super(task)
+	    @agent_model, @error = agent_model, error
+	end
+    end
+    
+    # Add a suitable execution agent to +task+ if its model has a execution
+    # agent model (see ModelLevelExecutionAgent), either by reusing one
+    # that is already in the plan, or by creating a new one.
+    def ExecutionAgent.spawn(task)
+	agent_model = task.model.execution_agent
+	candidates = task.plan.find_tasks.
+	    with_model(agent_model).
+	    self_owned.
+	    not_finished
+
+	agent = nil
+
+	if candidates.empty?
+	    begin
+		agent = agent_model.new
+		agent.on(:stop) do
+		    agent.each_executed_task do |task|
+			if task.running?
+			    task.emit(:aborted, "execution agent #{self} failed") 
+			elsif task.pending?
+			    task.remove_execution_agent agent
+			    spawn(task)
+			end
+		    end
+		end
+	    rescue Exception => e
+		Roby::Propagation.add_error(ExecutionAgentSpawningFailed.new(task, agent_model, e))
+	    end
+	else
+	    running, pending = candidates.partition { |t| t.running? }
+	    agent = if running.empty? then pending.first
+		    else running.first
+		    end
+	end
+	task.executed_by agent
+	agent
+    end
+
+    # This module is hooked in Roby::TaskEventGenerator to check that a task
+    # which is being started has a suitable execution agent, and to start it if
+    # it's not the case
+    module ExecutionAgentStart
+	def calling(context)
+	    super if defined? super
+	    return unless symbol == :start
+	    return unless agent = task.execution_agent
+
+	    if agent.finished? || agent.finishing?
+		raise CommandFailed.new(nil, self), "task #{task} has an execution agent but it is dead"
+	    elsif !agent.event(:ready).happened? && !agent.depends_on?(task)
+		postpone(agent.event(:ready), "spawning execution agent #{agent} for #{self}") do
+		    if agent.pending?
+			agent.event(:ready).if_unreachable(true) do |reason|
+			    self.emit_failed "execution agent #{agent} failed to initialize: #{reason}"
+			end
+			agent.start!
+		    end
+		end
+	    end
+	end
+    end
+    Roby::TaskEventGenerator.include ExecutionAgentStart
+
+    # This module is included in Roby::Plan to automatically add execution agents
+    # to tasks that require it and are discovered in the executable plan.
+    module ExecutionAgentSpawn
+	# Hook into plan discovery to add execution agents to new tasks. 
+	# See ExecutionAgentSpawn.spawn
+	def discovered_tasks(tasks)
+	    # For now, settle on adding the execution agents only in the
+	    # main plan. Otherwise, it is possible that two transactions
+	    # will try to add two different agents
+	    #
+	    # Note that it would be solved by plan merging ...
+	    return unless executable?
+
+	    for task in tasks
+		if !task.execution_agent && task.model.execution_agent && task.self_owned?
+		    ExecutionAgent.spawn(task)
+		end
+	    end
+	end
+    end
+    Roby::Plan.include ExecutionAgentSpawn
+end
+

data/lib/roby/relations/hierarchy.rb

@@ -0,0 +1,239 @@
+require 'roby/task'
+require 'roby/control'
+require 'set'
+
+module Roby::TaskStructure
+    # Document-module: Hierarchy
+    relation :Hierarchy, :child_name => :child, :parent_name => :parent_task do
+	# True if +obj+ is a parent of this object in the hierarchy relation
+	# (+obj+ is realized by +self+)
+	def realizes?(obj);	parent_object?(obj, Hierarchy) end
+	# True if +obj+ is a child of this object in the hierarchy relation
+	def realized_by?(obj);  child_object?(obj, Hierarchy) end
+	# True if +obj+ can be reached through the Hierarchy relation by
+	# starting from this object
+	def depends_on?(obj)
+	    generated_subgraph(Hierarchy).include?(obj)
+	end
+	# The set of parent objects in the Hierarchy relation
+	def parents; parent_objects(Hierarchy) end
+	# The set of child objects in the Hierarchy relation
+	def children; child_objects(Hierarchy) end
+
+
+	# Adds +task+ as a child of +self+ in the Hierarchy relation. The
+	# following options are allowed:
+	#
+	# success:: the list of success events. The default is [:success]
+	# failure:: the list of failing events. The default is [:failed]
+	# model:: a <tt>[task_model, arguments]</tt> pair which defines the task model the parent is expecting. 
+	#   The default value is to get these parameters from +task+
+        #
+        # The +success+ set describes the events of the child task that are
+        # _required_ by the parent task. More specifically, the child task
+        # remains useful for the parent task as long as none of these events are
+        # emitted. By default, it is the +success+ event. Of course, an error
+        # condition is encountered when all events of +success+ become
+        # unreachable. In addition, the relation is removed if the
+        # +remove_when_done+ flag is set to true (false by default).
+        #
+        # The +failure+ set describes the events of the child task which are an
+        # error condition from the parent task point of view.
+        #
+        # In both error cases, a +ChildFailedError+ exception is raised.
+        def realized_by(task, options = {})
+            options = validate_options options, 
+		:model => [task.model, task.meaningful_arguments], 
+		:success => [:success], 
+		:failure => [:failed],
+		:remove_when_done => false
+
+	    options[:success] = Array[*options[:success]]
+	    options[:failure] = Array[*options[:failure]]
+
+	    # Validate failure and success event names
+	    options[:success].each { |ev| task.event(ev) }
+	    options[:failure].each { |ev| task.event(ev) }
+
+	    options[:model] = [options[:model], {}] unless Array === options[:model]
+	    required_model, required_args = *options[:model]
+	    if !task.fullfills?(required_model, required_args)
+		raise ArgumentError, "task #{task} does not fullfills the provided model #{options[:model]}"
+	    end
+
+	    add_child(task, options)
+            self
+        end
+
+	# Set up the event gathering needed by Hierarchy.check_structure
+	def added_child_object(child, relations, info) # :nodoc:
+	    super if defined? super
+	    if relations.include?(Hierarchy) && !respond_to?(:__getobj__) && !child.respond_to?(:__getobj__)
+		events = info[:success].map { |ev| child.event(ev) }
+		events.concat info[:failure].map { |ev| child.event(ev) }
+		Roby::EventGenerator.gather_events(Hierarchy.interesting_events, events)
+	    end
+	end
+
+	# Return the set of this task children for which the :start event has
+	# no parent in CausalLinks
+        def first_children
+	    result = ValueSet.new
+
+	    generated_subgraph(Hierarchy).each do |task|
+		next if task == self
+		if task.event(:start).root?(Roby::EventStructure::CausalLink)
+		    result << task
+		end
+	    end
+	    result
+        end
+
+	# The set of events that are needed by the parent tasks
+	def fullfilled_events
+	    needed = ValueSet.new
+	    each_parent_task do |parent|
+		needed.merge(parent[self, Hierarchy][:success])
+	    end
+	    needed
+	end
+
+	# Return [tags, arguments] where +tags+ is a list of task models which
+	# are required by the parent tasks of this task, and arguments the
+	# required arguments
+	#
+	# If there is a task class in the required models, it is always the
+	# first element of +tags+
+	def fullfilled_model
+	    model, tags, arguments = Roby::Task, [], {}
+
+	    each_parent_task do |parent|
+		m, a = parent[self, Hierarchy][:model]
+		if m.instance_of?(Roby::TaskModelTag)
+		    tags << m
+		elsif m.has_ancestor?(model)
+		    model = m
+		elsif !model.has_ancestor?(m)
+		    raise "inconsistency in fullfilled models: #{model} and #{m} are incompatible"
+		end
+		a.merge!(arguments) do |old, new| 
+		    if old != new
+			raise "inconsistency in fullfilled models: #{old} and #{new}"
+		    end
+		end
+	    end
+
+	    tags.unshift(model)
+	    [tags, arguments]
+	end
+
+	# Remove all children that have successfully finished
+	def remove_finished_children
+	    # We call #to_a to get a copy of children, since we will remove
+	    # children in the block. Note that we can't use #delete_if here
+	    # since #children is a relation enumerator (not the relation list
+	    # itself)
+	    children.to_a.each do |child|
+		success_events = self[child, Hierarchy][:success]
+		if success_events.any? { |ev| child.event(ev).happened? }
+		    remove_child(child)
+		end
+	    end
+	end
+    end
+
+    # Checks the structure of +plan+ w.r.t. the constraints of the hierarchy
+    # relations. It returns an array of ChildFailedError for all failed
+    # hierarchy relations
+    def Hierarchy.check_structure(plan)
+	result = []
+
+	events = Hierarchy.interesting_events
+	return result if events.empty? && failing_tasks.empty?
+
+	# Get the set of tasks for which a possible failure has been
+	# registered The tasks that are failing the hierarchy requirements
+	# are registered in Hierarchy.failing_tasks. The interesting_events
+	# set is cleared at cycle end (see below)
+	tasks = events.inject(failing_tasks) { |set, event| set << event.generator.task }
+	@failing_tasks = ValueSet.new
+	tasks.each do |child|
+	    # Check if the task has been removed from the plan
+	    next unless child.plan
+
+	    has_error = false
+	    child.each_parent_task do |parent|
+		next unless parent.self_owned?
+		next if parent.finished? || parent.finishing?
+
+		options = parent[child, Hierarchy]
+		success = options[:success]
+		failure = options[:failure]
+
+		if success.any? { |e| child.event(e).happened? }
+		    if options[:remove_when_done]
+			parent.remove_child child
+		    end
+		elsif failing_event = failure.find { |e| child.event(e).happened? }
+		    result << Roby::ChildFailedError.new(parent, child.event(failing_event).last)
+		    failing_tasks << child
+		end
+	    end
+	end
+
+	events.clear
+	result
+    end
+
+    class << Hierarchy
+	# The set of events that have been fired in this cycle and are involved in a Hierarchy relation
+	attribute(:interesting_events) { Array.new }
+
+	# The set of tasks that are currently failing 
+	attribute(:failing_tasks) { ValueSet.new }
+    end
+end
+
+module Roby
+    # This exception is raised when a {hierarchy relation}[classes/Roby/TaskStructure/Hierarchy.html] fails
+    class ChildFailedError < LocalizedError
+	# The parent in the relation
+	attr_reader :parent
+	# The child in the relation
+	def child; failed_task end
+	# The relation parameters (i.e. the hash given to #realized_by)
+	attr_reader :relation
+
+	# The event which is the cause of this error. This is either the task
+	# source of a failure event, or the reason why a positive event has
+	# become unreachable (if there is one)
+	def initialize(parent, event)
+	    super(event.task_sources.find { true })
+	    @parent = parent
+	    @relation = parent[child, TaskStructure::Hierarchy]
+	end
+
+	def pretty_print(pp) # :nodoc:
+            super
+            pp.breakable
+            pp.breakable
+            pp.text "The failed relation is"
+            pp.breakable
+            pp.nest(2) do
+                pp.text "  "
+                parent.pretty_print pp
+                pp.breakable
+                pp.text "realized_by "
+                child.pretty_print pp
+            end
+	end
+	def backtrace; [] end
+
+        # True if +obj+ is involved in this exception
+        def involved_plan_object?(obj)
+            super || obj == parent
+        end
+    end
+    Control.structure_checks << TaskStructure::Hierarchy.method(:check_structure)
+end
+