roby 0.7.3 → 0.8.0

data/lib/roby/task.rb

@@ -1,17 +1,14 @@
-require 'roby/plan-object'
-require 'roby/exceptions'
-require 'roby/event'
-require 'utilrb/module/attr_predicate'
-
 module Roby
     class TaskModelTag < Module
 	module ClassExtension
 	    # Returns the list of static arguments required by this task model
 	    def arguments(*new_arguments)
 		new_arguments.each do |arg_name|
+                    arg_name = arg_name.to_sym
 		    argument_set << arg_name.to_sym
 		    unless method_defined?(arg_name)
 			define_method(arg_name) { arguments[arg_name] }
+			define_method("#{arg_name}=") { |value| arguments[arg_name] = value }
 		    end
 		end
 
@@ -19,6 +16,27 @@ module Roby
 	    end
 	    # Declares a set of arguments required by this task model
 	    def argument(*args); arguments(*args) end
+            # The part of +arguments+ that is meaningful for this task model
+            def meaningful_arguments(arguments)
+                self_arguments = self.arguments.to_set
+                arguments.to_hash.delete_if do |key, _|
+                    !self_arguments.include?(key)
+                end
+            end
+
+            # Checks if this model fullfills everything in +models+
+            def fullfills?(models)
+                if !models.respond_to?(:each)
+                    models = [models]
+                end
+
+                for tag in models
+                    if !has_ancestor?(tag)
+                        return false
+                    end
+                end
+                true
+            end
 	end
 	include TaskModelTag::ClassExtension
 
@@ -46,6 +64,8 @@ module Roby
         # The task which fired this event
         attr_reader :task
         
+        def model; self.class end
+
         def initialize(task, generator, propagation_id, context, time = Time.now)
             @task = task
 	    @terminal_flag = generator.terminal_flag
@@ -88,7 +108,7 @@ module Roby
         # responds to #call
         def self.controlable?; respond_to?(:call) end
         # If the event is controlable
-        def controlable?; self.class.controlable? end
+        def controlable?; model.controlable? end
 	class << self
 	    # Called by Task.update_terminal_flag to update the flag
 	    attr_writer :terminal
@@ -104,7 +124,7 @@ module Roby
         # The event symbol
         def self.symbol; @symbol end
         # The event symbol
-        def symbol; self.class.symbol end
+        def symbol; model.symbol end
     end
 
     # A task event model bound to a particular task instance
@@ -140,9 +160,22 @@ module Roby
 	# by task.plan=. It is redefined here for performance reasons.
 	attr_accessor :plan
 
-	# Fire the event
+	# Check that the event can be emitted
+        def emitting(context)
+            task.emitting_event(self, context)
+            super if defined? super
+        end
+
         def fire(event)
             task.fire_event(event)
+            super if defined? super
+        end
+
+        def emit_failed(*reason)
+            if symbol == :start
+                task.failed_to_start = true
+                task.plan.task_index.set_state(task, :failed?)
+            end
             super
         end
 
@@ -153,13 +186,13 @@ module Roby
 	    super if defined? super
             if task.finished? && !terminal?
                 raise CommandFailed.new(nil, self), 
-		    "#{symbol}!(#{context})) called by #{Propagation.sources} but the task has finished. Task has been terminated by #{task.event(:stop).history.first.sources}."
+		    "#{symbol}!(#{context}) called by #{plan.engine.propagation_sources.to_a} but the task has finished. Task has been terminated by #{task.event(:stop).history.first.sources}."
             elsif task.pending? && symbol != :start
                 raise CommandFailed.new(nil, self), 
-		    "#{symbol}!(#{context})) called by #{Propagation.sources} but the task is not running"
+		    "#{symbol}!(#{context}) called by #{plan.engine.propagation_sources.to_a} but the task has never been started"
             elsif task.running? && symbol == :start
                 raise CommandFailed.new(nil, self), 
-		    "#{symbol}!(#{context})) called by #{Propagation.sources} but the task is already running. Task has been started by #{task.event(:start).history.first.sources}."
+		    "#{symbol}!(#{context}) called by #{plan.engine.propagation_sources.to_a} but the task is already running. Task has been started by #{task.event(:start).history.first.sources}."
             end
 	end
 
@@ -219,7 +252,7 @@ module Roby
 		task.update_terminal_flag
 	    end
 	end
-        def new(context); event_model.new(task, self, Propagation.propagation_id, context) end
+        def new(context); event_model.new(task, self, plan.engine.propagation_id, context) end
 
 	def to_s
 	    "#{task}/#{symbol}"
@@ -238,8 +271,8 @@ module Roby
 				      end
 
 	    if child_task
-		unless task.realized_by?(child_task)
-		    task.realized_by child_task, 
+		unless task.depends_on?(child_task, false)
+		    task.depends_on child_task, 
 			:success => [child_event.symbol],
 			:remove_when_done => true
 		end
@@ -249,6 +282,13 @@ module Roby
 	    end
 	end
 
+	# Refines exceptions that may be thrown by #call_without_propagation
+        def call_without_propagation(context)
+            super
+    	rescue EventNotExecutable => e
+	    refine_exception(e)
+        end
+
 	# Checks that the event can be called. Raises various exception
 	# when it is not the case.
 	def check_call_validity
@@ -268,23 +308,29 @@ module Roby
 
 	def refine_exception (e)
 	    if task.partially_instanciated?
-		raise EventNotExecutable.new(self), "#{name}! called on #{task} which is partially instanciated\n" + 
+		raise EventNotExecutable.new(self), "#{symbol}! called on #{task} which is partially instanciated\n" + 
 			"The following arguments were not set: \n" +
 			task.list_unset_arguments.map {|n| "\t#{n}"}.join("\n")+"\n"
 # 						
 	    elsif !plan
-		raise EventNotExecutable.new(self), "#{name}! called on #{task} but the task is in no plan"
+		raise EventNotExecutable.new(self), "#{symbol}! called on #{task} but the task is in no plan"
 	    elsif !plan.executable?
-		raise EventNotExecutable.new(self), "#{name}! called on #{task} but the plan is not executable"
+		raise EventNotExecutable.new(self), "#{symbol}! called on #{task} but the plan is not executable"
 	    elsif task.abstract?
-		raise EventNotExecutable.new(self), "#{name}! called on #{task} but the task is abstract"
+		raise EventNotExecutable.new(self), "#{symbol}! called on #{task} but the task is abstract"
 	    else
-		raise EventNotExecutable.new(self), "#{name}! called on #{task} which is not executable: #{e.message}"
+		raise EventNotExecutable.new(self), "#{symbol}! called on #{task} which is not executable: #{e.message}"
 	    end
 	end
 
     end
 
+    # Class that handles task arguments. They are handled specially as the
+    # arguments cannot be overwritten and can not be changed by a task that is
+    # not owned.
+    #
+    # Moreover, two hooks #updating and #updated allow to hook into the argument
+    # update system.
     class TaskArguments < Hash
 	private :delete, :delete_if
 
@@ -305,6 +351,7 @@ module Roby
 
 	alias :update! :[]=
 	def []=(key, value)
+            key = key.to_sym if key.respond_to?(:to_str)
 	    if writable?(key)
 		if !task.read_write?
 		    raise OwnershipError, "cannot change the argument set of a task which is not owned #{task} is owned by #{task.owners} and #{task.plan} by #{task.plan.owners}"
@@ -320,6 +367,11 @@ module Roby
 	def updating; super if defined? super end
 	def updated; super if defined? super end
 
+        def [](key)
+            key = key.to_sym if key.respond_to?(:to_str)
+            super(key)
+        end
+
 	alias :do_merge! :merge!
 	def merge!(hash)
 	    super do |key, old, new|
@@ -363,7 +415,7 @@ module Roby
     #       end
     #
     #       event :other_event do |context|
-    #           Roby.once { emit :other_event }
+    #           engine.once { emit :other_event }
     #       end
     #   end
     #
@@ -371,6 +423,13 @@ module Roby
     # immediately emitted, and in the second case it will be emitted at the
     # beginning of the next execution cycle.
     #
+    # === Task relations
+    #
+    # Task relations are defined in the TaskStructure RelationSpace instance.
+    # See TaskStructure documentation for the list of special methods defined
+    # by the various graphs, and the TaskStructure namespace for the name and
+    # purpose of the various relation graphs themselves.
+    #
     # === Executability
     #
     # By default, a task is not executable, which means that no event command
@@ -420,7 +479,7 @@ module Roby
 	    class_eval do
 		# Remove event models
 		events.each_key do |ev_symbol|
-		    remove_const ev_symbol.to_s.camelize
+		    remove_const ev_symbol.to_s.camelcase(true)
 		end
 
 		[@events, @signal_sets, @forwarding_sets, @causal_link_sets,
@@ -461,6 +520,123 @@ module Roby
 	    EOD
 	end
 
+        ## 
+        # :singleton-method: signals
+        # :call-seq:
+        #   task_model.signals(event_model) => [target_event_models]
+        #
+        # Returns the set of model-level signal targets for the given event.
+
+        ## 
+        # :singleton-method: each_signal
+        # :call-seq:
+        #   task_model.each_signal(event_model) do |target_event_model|
+        #   end
+        #
+        # Enumerates the set of model-level causal links that are defined for
+        # the given event. It enumerates all the ones defined on this model
+        # (using Task::signal) and also on its parent classes.
+
+        ## 
+        # :method: each_signal
+        # :call-seq:
+        #   task.each_signal(event_model) do |target_event_model|
+        #   end
+        #
+        # Enumerates the set of model-level causal links that are defined for
+        # the given event. It enumerates all the ones defined on this task's model
+        # (using Task::signal) and also on its parent classes.
+
+
+
+
+        ## 
+        # :singleton-method: forwardings
+        # :call-seq:
+        #   task_model.forwardings(event_model) => [target_event_models]
+        #
+        # Returns the set of model-level forwarding targets for the given event.
+
+        ## 
+        # :singleton-method: each_forwarding
+        # :call-seq:
+        #   task_model.each_forwarding(event_model) do |target_event_model|
+        #   end
+        #
+        # Enumerates the set of model-level causal links that are defined for
+        # the given event. It enumerates all the ones defined on this model
+        # (using Task::forward) and also on its parent classes.
+
+        ## 
+        # :method: each_forwarding
+        # :call-seq:
+        #   task.each_forwarding(event_model) do |target_event_model|
+        #   end
+        #
+        # Enumerates the set of model-level causal links that are defined for
+        # the given event. It enumerates all the ones defined on this task's
+        # model (using Task::forward) and also on its parent classes.
+
+
+
+
+        ## 
+        # :singleton-method: causal_links
+        # :call-seq:
+        #   task_model.causal_links(event_model) => [target_event_models]
+        #
+        # Returns the set of model-level causal_link targets for the given event.
+
+        ## 
+        # :singleton-method: each_causal_link
+        # :call-seq:
+        #   task_model.each_causal_link(event_model) do |target_event_model|
+        #   end
+        #
+        # Enumerates the set of model-level causal links that are defined for
+        # the given event. It enumerates all the ones defined on this model
+        # (using Task::causal_link) and also on its parent classes.
+
+        ## 
+        # :method: each_causal_link
+        # :call-seq:
+        #   task.each_causal_link(event_model) do |target_event_model|
+        #   end
+        #
+        # Enumerates the set of model-level causal links that are defined for
+        # the given event. It enumerates all the ones defined on this task's model
+        # (using Task::causal_link) and also on its parent classes.
+
+
+
+
+        ## 
+        # :singleton-method: handlers
+        # :call-seq:
+        #   task_model.handlers(event_model) => [target_event_models]
+        #
+        # Returns the set of model-level event handlers for the given event.
+
+        ## 
+        # :singleton-method: each_handler
+        # :call-seq:
+        #   task_model.each_handler(event_model) do |target_event_model|
+        #   end
+        #
+        # Enumerates the set of model-level event handlers that are defined for
+        # the given event. It enumerates all handlers defined on the instance's
+        # task model and its parent classes.
+
+        ## 
+        # :method: each_handler
+        # :call-seq:
+        #   task.each_handler(event_model) do |target_event_model|
+        #   end
+        #
+        # Enumerates the set of model-level event handlers that are defined for
+        # the given event. It enumerates all handlers defined on the instance's
+        # task model and its parent classes.
+
 	model_attribute_list('signal')
 	model_attribute_list('forwarding')
 	model_attribute_list('causal_link')
@@ -469,13 +645,17 @@ module Roby
 
 	# The task arguments as symbol => value associative container
 	attr_reader :arguments
-	# The part of +arguments+ that is meaningful for this task model
+
+	# The part of +arguments+ that is meaningful for this task model. I.e.
+        # it returns the set of elements in the +arguments+ property that define
+        # arguments listed in the task model
 	def meaningful_arguments(task_model = self.model)
 	    arguments.slice(*task_model.arguments)
 	end
+
 	# The task name
 	def name
-	    @name ||= "#{model.name || self.class.name}#{arguments.to_s}:0x#{address.to_s(16)}"
+	    @name ||= "#{model.name || self.class.name}:0x#{address.to_s(16)}"
 	end
 	
 	# This predicate is true if this task is a mission for its owners. If
@@ -484,6 +664,7 @@ module Roby
 
 	def inspect
 	    state = if pending? then 'pending'
+		    elsif failed_to_start? then 'failed to start'
 		    elsif starting? then 'starting'
 		    elsif running? then 'running'
 		    elsif finishing? then 'finishing'
@@ -499,23 +680,34 @@ module Roby
         # * the task shall have a +start+ event
         # * the task shall have at least one terminal event. If no +stop+ event
         #   is defined, then all terminal events are aliased to +stop+
-        def initialize(arguments = nil) #:yields: task_object
+        def initialize(arguments = Hash.new) #:yields: task_object
 	    super() if defined? super
 
 	    @arguments = TaskArguments.new(self)
-	    @arguments.merge!(arguments) if arguments
+            arguments.each do |key, value|
+                if self.respond_to?("#{key}=")
+                    self.send("#{key}=", value)
+                else
+                    @arguments[key] = value
+                end
+            end
 
 	    @model = self.class
 
             yield(self) if block_given?
+            # Create the EventGenerator instances that represent this task's
+            # events. Note that the event relations are instanciated by
+            # Plan#discover when this task is included in a plan, thus avoiding
+            # filling up the relation graphs with unused relations.
 	    initialize_events
 	end
 
 
         # Lists all arguments, that are set to be needed via the :argument 
         # syntax but are not set.
+        #
         # This is needed for debugging purposes.
-        def list_unset_arguments
+        def list_unset_arguments # :nodoc:
             ret = Array.new
             model.arguments.each { |name| 
                   if !arguments.has_key?(name) then 
@@ -523,7 +715,6 @@ module Roby
                   end }
             ret
         end
-            
 
         # Helper methods which creates all the necessary TaskEventGenerator
         # objects and stores them in the #bound_events map
@@ -540,6 +731,25 @@ module Roby
 
 	def model; self.class end
 
+	# Returns for how many seconds this task is running.  Returns nil if
+	# the task is not running.
+	def lifetime
+	    if running?
+		Time.now - history.first.time
+	    end
+	end
+
+        # Returns when this task has been started
+        def start_time
+            if running?
+                history.first.time
+            end
+        end
+
+        def create_fresh_copy
+	    model.new(arguments.dup)
+        end
+
 	def initialize_copy(old) # :nodoc:
 	    super
 
@@ -551,7 +761,7 @@ module Roby
 	    arguments.instance_variable_set(:@task, self)
 
 	    initialize_events
-	    plan.discover(self)
+	    plan.add(self)
 	end
 
 	def instantiate_model_event_relations
@@ -569,7 +779,7 @@ module Roby
 
 	        for signalled in signalled_events
 	            signalled = bound_events[signalled]
-	            generator.signal signalled
+	            generator.signals signalled
 	            left_border.delete(signalled)
 	        end
 	    end
@@ -582,7 +792,7 @@ module Roby
 
 	        for signalled in signalled_events
 	            signalled = bound_events[signalled]
-	            generator.forward signalled
+	            generator.forward_to signalled
 	            left_border.delete(signalled)
 	        end
 	    end
@@ -646,29 +856,44 @@ module Roby
 	end
 
 	class << self
-	    # If this task is an abstract task
-	    # Abstract tasks are not executable. This attribute is
-	    # not inherited in the task hierarchy
-	    attr_reader :abstract
-	    alias :abstract? :abstract
-
-	    # Mark this task model as an abstract model
+            ##
+            # :singleton-method: abstract?
+            #
+            # True if this task is an abstract task.
+            #
+            # See Task::abstract() for more information.
+            attr_predicate :abstract
+
+	    # Declare that this task model defines abstract tasks. Abstract
+            # tasks can be used to represent an action, without specifically
+            # representing how this action should be done.
+            #
+            # Instances of abstract task models are not executable, i.e. they
+            # cannot be started.
+            #
+            # See also #abstract? and #executable?
 	    def abstract
 		@abstract = true
 	    end
 
-            # Declare that nothing special is required to stop this task.
-            # This makes +failed+ and +stop+ controlable events, and
-            # makes the interruption sequence be stop! => calls failed! =>
-            # emits +failed+ => emits +stop+.
+            # Declare that tasks of this model can finish by simply emitting
+            # +stop+. Use it this way:
+            #
+            #   class MyTask < Roby::Task
+            #     terminates
+            #   end
+            #
+            # It adds a +stop!+ command that emits the +failed+ event.
 	    def terminates
 		event :failed, :command => true, :terminal => true
 		interruptible
 	    end
 
-            # Sets up a command for +stop+ in the case where +failed+ is also
-            # controllable, if the command of +failed+ should be used to stop
-            # the task.
+            # Declare that tasks of this model can be interrupted. It does so by
+            # defining a command for +stop+, which in effect calls the command
+            # for +failed+.
+            #
+            # Raises ArgumentError if failed is not controlable.
 	    def interruptible
 		if !has_event?(:failed) || !event_model(:failed).controlable?
 		    raise ArgumentError, "failed is not controlable"
@@ -683,7 +908,7 @@ module Roby
 	    end
 
 	    def setup_poll_method(block) # :nodoc:
-		define_method(:poll) do
+		define_method(:poll) do |plan|
 		    return unless self_owned?
 		    begin
 			poll_handler
@@ -695,9 +920,17 @@ module Roby
 		define_method(:poll_handler, &block)
 	    end
 
-            # Defines a block which will be called at each execution cycle for
-            # each running task of this model. The block is called in the
-            # instance context of the target task (i.e. using instance_eval)
+            # Declares that the given block should be called at each execution
+            # cycle, when the task is running. Use it that way:
+            #
+            #   class MyTask < Roby::Task
+            #     poll do
+            #       ... do something ...
+            #     end
+            #   end
+            #
+            # If the given polling block raises an exception, the task will be
+            # terminated by emitting its +failed+ event.
 	    def poll(&block)
 		if !block_given?
 		    raise "no block given"
@@ -705,8 +938,8 @@ module Roby
 
 		setup_poll_method(block)
 
-		on(:start) { Control.event_processing << method(:poll) }
-		on(:stop)  { Control.event_processing.delete(method(:poll)) }
+		on(:start) { |ev| ev.task.plan.engine.propagation_handlers << method(:poll) }
+		on(:stop)  { |ev| ev.task.plan.engine.propagation_handlers.delete(method(:poll)) }
 	    end
 	end
 
@@ -715,8 +948,13 @@ module Roby
         
         # Returns true if this task is from an abstract model. If it is the
         # case, the task is not executable.
-	def abstract?; self.class.abstract? end
-	# Check if this task is executable
+        #
+        # See Task::abstract for more details.
+	def abstract?; model.abstract? end
+	# True if this task is executable. A task is not executable if it is
+        # abstract or partially instanciated.
+        #
+        # See #abstract? and #partially_instanciated?
 	def executable?; !abstract? && !partially_instanciated? && super end
 	# Returns true if this task's stop event is controlable
 	def interruptible?; event(:stop).controlable? end
@@ -745,14 +983,14 @@ module Roby
         # can either be a event class or an event name.
         def has_event?(event_model)
 	    bound_events.has_key?(event_model) ||
-		self.class.has_event?(event_model)
+		model.has_event?(event_model)
 	end
         
         # True if this task is starting, i.e. if its start event is pending
         # (has been called, but is not emitted yet)
 	def starting?; event(:start).pending? end
 	# True if this task has never been started
-	def pending?; !starting? && !started? end
+	def pending?; !failed_to_start? && !starting? && !started? end
         # True if this task is currently running (i.e. is has already started,
         # and is not finished)
         def running?; started? && !finished? end
@@ -767,14 +1005,24 @@ module Roby
 	attr_predicate :started?, true
 	attr_predicate :finished?, true
 	attr_predicate :success?, true
+	attr_predicate :failed_to_start?, true
 
         # True if the +failed+ event of this task has been fired
-	def failed?; finished? && @success == false end
+	def failed?; failed_to_start? || (finished? && @success == false) end
 
-	# Remove all relations in which +self+ or its event are involved
-	def clear_relations
-	    each_event { |ev| ev.clear_relations }
-	    super
+	# call-seq:
+        #   task.clear_relations => task
+        #
+        # Remove all relations in which +self+ or its event are involved
+        #--
+        # The including_events flag is here for the benefit of
+        # Transactions::Proxy::Task only
+	def clear_relations(including_events = true)
+            if including_events
+                each_event { |ev| ev.clear_relations }
+            end
+	    super()
+            self
 	end
 
         # Update the terminal flag for the event models that are defined in
@@ -863,8 +1111,8 @@ module Roby
 	    end
 	end
 
-        # Returns a sorted list of Event objects, for all events that have been
-        # fired by this task
+        # Returns a list of Event objects, for all events that have been fired
+        # by this task. The list is sorted by emission times.
 	def history
 	    history = []
 	    each_event do |event|
@@ -874,9 +1122,9 @@ module Roby
 	    history.sort_by { |ev| ev.time }
 	end
 
-        # Returns the set of tasks directly related to this task, either
-        # because of task relations or because of task events that are related
-        # to other task events
+        # Returns the set of tasks directly related to this task, either because
+        # of task relations or because of task events that are related to other
+        # task events
 	def related_tasks(result = nil)
 	    result = related_objects(nil, result)
 	    each_event do |ev|
@@ -898,29 +1146,41 @@ module Roby
             
         # This method is called by TaskEventGenerator#fire just before the event handlers
         # and commands are called
-        def fire_event(event) # :nodoc:
+        def emitting_event(event, context) # :nodoc:
 	    if !executable?
-		raise TaskNotExecutable.new(self), "trying to fire #{event.generator.symbol} on #{self} but #{self} is not executable"
+		raise TaskNotExecutable.new(self), "trying to emit #{symbol} on #{self} but #{self} is not executable"
 	    end
 
             if finished? && !event.terminal?
-                raise EmissionFailed.new(nil, self), 
-		    "emit(#{event.symbol}: #{event.model}[#{event.context}]) called @#{event.propagation_id} by #{Propagation.sources} but the task has finished. Task has been terminated by #{event(:stop).history.first.sources}."
+                raise EmissionFailed.new(nil, self),
+		    "emit(#{event.symbol}, #{context}) called by #{plan.engine.propagation_sources.to_a} but the task has finished. Task has been terminated by #{event(:stop).history.first.sources}."
             elsif pending? && event.symbol != :start
-                raise EmissionFailed.new(nil, self), 
-		    "emit(#{event.symbol}: #{event.model}[#{event.context}]) called @#{event.propagation_id} by #{Propagation.sources} but the task is not running"
+                raise EmissionFailed.new(nil, self),
+		    "emit(#{event.symbol}, #{context}) called by #{plan.engine.propagation_sources.to_a} but the task has never been started"
             elsif running? && event.symbol == :start
-                raise EmissionFailed.new(nil, self), 
-		    "emit(#{event.symbol}: #{event.model}[#{event.context}]) called @#{event.propagation_id} by #{Propagation.sources} but the task is already running. Task has been started by #{event(:start).history.first.sources}."
+                raise EmissionFailed.new(nil, self),
+		    "emit(#{event.symbol}, #{context}) called by #{plan.engine.propagation_sources.to_a} but the task is already running. Task has been started by #{event(:start).history.first.sources}."
             end
 
-	    update_task_status(event)
+	    super if defined? super
+        end
 
+        # Hook called by TaskEventGenerator#fired when one of this task's events
+        # is fired.
+        def fire_event(event)
+	    update_task_status(event)
 	    super if defined? super
         end
 
 	# The event which has finished the task (if there is one)
 	attr_reader :terminal_event
+
+        # The event that caused this task to fail. This is equivalent to taking
+        # the first emitted element of
+        #   task.event(:failed).last.task_sources
+        #
+        # It is only much more efficient
+        attr_reader :failure_event
 	
 	# Call to update the task status because of +event+
 	def update_task_status(event) # :nodoc:
@@ -934,6 +1194,7 @@ module Roby
 		self.success = false
 		self.finished = true
 		@terminal_event ||= event
+                @failure_event  ||= event
 	    elsif event.terminal? && !finished?
 		plan.task_index.set_state(self, :finished?)
 		self.finished = true
@@ -974,22 +1235,42 @@ module Roby
         end
 
         # call-seq:
-        #   on(event, task[, event1, event2, ...])
 	#   on(event) { |event| ... }
-        #   on(event[, task, event1, event2, ...]) { |event| ... }
-        #   on(event, task[, event1, event2, ...], delay)
-        #
-        # Adds a signal from the given event to the specified targets, and/or
-        # defines an event handler. Note that <tt>on(event, task)</tt> is
-        # equivalent to <tt>on(event, task, event)</tt>
         #
-        # +delay+, if given, specifies that the signal must be postponed for as
-        # much time as specified. See EventGenerator#signal for valid values.
+        # Defines an event handler for the given event.
         def on(event_model, to = nil, *to_task_events, &user_handler)
-            unless to || user_handler
+            if to
+                Roby.warn_deprecated "on(event_name, task, target_events) has been replaced by #signals"
+            elsif !(to || user_handler)
                 raise ArgumentError, "you must provide either a task or an event handler (got nil for both)"
             end
 
+            if to
+                signals(event_model, to, *to_task_events)
+            end
+            if user_handler
+                generator = event(event_model)
+                generator.on(&user_handler)
+            end
+            self
+        end
+
+        # call-seq:
+        #   signals source_event, dest_task, ev1, ev2, ev3, ...
+        #   signals source_event, dest_task, ev1, ev2, ev3, delay_options
+        #
+        # Creates a signal from +source_event+, which is an event name of
+        # +self+, to the listed events of +dest_task+. The destination events
+        # will be called when the source event is emitted.
+        #
+        # To simply emit target events (i.e. not calling the event's commands),
+        # use #forwards
+        #
+        # Optionally, a delay can be added to the signal. +delay_options+ can be
+        # either:
+        #   :delay => relative_delay_in_seconds
+        #   :at => absolute_time
+        def signals(event_model, to, *to_task_events)
             generator = event(event_model)
             if Hash === to_task_events.last
                 delay = to_task_events.pop
@@ -997,6 +1278,7 @@ module Roby
 	    to_events = case to
 			when Task
 			    if to_task_events.empty?
+                                Roby.warn_deprecated "signals(event_name, target_task) is deprecated. You must now always specify the target event name"
 				[to.event(generator.symbol)]
 			    else
 				to_task_events.map { |ev_model| to.event(ev_model) }
@@ -1006,27 +1288,35 @@ module Roby
 			end
 
             to_events.push delay if delay
-            generator.on(*to_events, &user_handler)
+            generator.signals(*to_events)
             self
         end
 
+	def forward(name, to, *to_task_events)
+            Roby.warn_deprecated "Task#forward has been renamed into Task#forward_to"
+            if to_task_events.empty?
+                Roby.warn_deprecated "the Task#forward(event_name, target_task) form is deprecated. Use Task#forward_to and specify the target event name"
+            end
+
+            forward_to(name, to, *to_task_events)
+        end
+
         # call-seq:
-        #   forward source_event, dest_task, ev1, ev2, ev3, ...
-        #   forward source_event, dest_task, ev1, ev2, ev3, delay_options
+        #   forward_to source_event, dest_task, ev1, ev2, ev3, ...
+        #   forward_to source_event, dest_task, ev1, ev2, ev3, delay_options
         #
-        # Fowards +name+ to the events in +to_task_events+ on task +to+.  The
-        # target events will be emitted as soon as the +name+ event is emitted
-        # on the receiving task, without calling any command.
+        # Fowards the +source_event+, which is the name of an event of +self+,
+        # to the listed events in +dest_task+. The target events will be emitted
+        # as soon as the source event is emitted,
         #
         # To call an event whenever other events are emitted, use the Signal
-        # relation. See Task#on, Task.on and EventGenerator#on. As for Task#on,
-        # <tt>forward(:start, task)</tt> is a shortcut to <tt>forward(:start,
-        # task, :start)</tt>.
+        # relation. See Task#signals, Task.signal and EventGenerator#signals.
         #
-        # If a +delay_options+ hash is provided, the forwarding is not performed
-        # immediately, but with a given delay. See EventGenerator#forward for
-        # the delay specification.
-	def forward(name, to, *to_task_events)
+        # Optionally, a delay can be added to the signal. +delay_options+ can be
+        # either:
+        #   :delay => relative_delay_in_seconds
+        #   :at => absolute_time
+	def forward_to(name, to, *to_task_events)
             generator = event(name)
             if Hash === to_task_events.last
                 delay = to_task_events.pop
@@ -1034,10 +1324,11 @@ module Roby
 
 	    to_events = if to.respond_to?(:event)
 			    if to_task_events.empty?
+                                Roby.warn_deprecated "forward_to(event_name, target_task) is deprecated. You must now always specify the target event name"
 				[to.event(generator.symbol)]
-			    else
-				to_task_events.map { |ev| to.event(ev) }
-			    end
+                            else
+                                to_task_events.map { |ev| to.event(ev) }
+                            end
 			elsif to.kind_of?(EventGenerator)
 			    [to]
 			else
@@ -1045,31 +1336,44 @@ module Roby
 			end
 
 	    to_events.each do |ev|
-		generator.forward ev, delay
+		generator.forward_to ev, delay
 	    end
 	end
 
+        # :stopdoc:
 	attr_accessor :calling_event
+
 	def method_missing(name, *args, &block) # :nodoc:
 	    if calling_event && calling_event.respond_to?(name)
 		calling_event.send(name, *args, &block)
 	    else
 		super
 	    end
-	rescue
-	    raise $!, $!.message, $!.backtrace[1..-1]
+	rescue NameError => e
+	    raise e, e.message, caller(1)
+	rescue NoMethodError => e
+	    raise e, e.message, caller(1)
 	end
 
+        # Declares that this task model provides the given interface. +model+
+        # must be an instance of TaskModelTag
+        def self.provides(model)
+            include model
+        end
+
+
 	@@event_command_id = 0
 	def self.allocate_event_command_id # :nodoc:
 	    @@event_command_id += 1
 	end
+        # :startdoc:
+
         # call-seq:
-        #   self.event(name, options = nil) { ... } -> event class or nil
+        #   self.event(name, options = nil) { ... } => event class or nil
         #
         # Define a new event in this task. 
         #
-        # ==== Available options
+        # <b>Available options</b>
         #
         # <tt>command</tt>::
         #   either true, false or an event command for the new event. In that
@@ -1086,7 +1390,7 @@ module Roby
         #   base class for the event model (see "Event models" below). The default is the 
         #   TaskEvent class
         #
-        # ==== Event models
+        # <b>Event models</b>
         #
         # When a task event (for instance +start+) is emitted, a Roby::Event
         # object is created to describe the information related to this
@@ -1130,10 +1434,10 @@ module Roby
                 @symbol   = ev
                 @command_handler = command_handler
 
-		define_method(:name) { "#{task.name}::#{ev_s.camelize}" }
+		define_method(:name) { "#{task.name}::#{ev_s.camelcase(true)}" }
                 singleton_class.class_eval do
                     attr_reader :command_handler
-		    define_method(:name) { "#{task_klass.name}::#{ev_s.camelize}" }
+		    define_method(:name) { "#{task_klass.name}::#{ev_s.camelcase(true)}" }
 		    def to_s; name end
                 end
             end
@@ -1148,7 +1452,7 @@ module Roby
 	    if setup_terminal_handler
 		forward(new_event => :stop)
 	    end
-	    const_set(ev_s.camelize, new_event)
+	    const_set(ev_s.camelcase(true), new_event)
 
 	    if options[:command]
 		# check that the supplied command handler can take two arguments
@@ -1172,6 +1476,17 @@ module Roby
 		end
             end
 
+            if !method_defined?("#{ev_s}_event")
+                define_method("#{ev_s}_event") do
+                    event(ev)
+                end
+            end
+            if !method_defined?("#{ev_s}?")
+                define_method("#{ev_s}?") do
+                    event(ev).happened?
+                end
+            end
+
 	    new_event
         end
 
@@ -1201,15 +1516,23 @@ module Roby
 
         # Events defined by the task model
         inherited_enumerable(:event, :events, :map => true) { Hash.new }
-	def self.enum_events
+
+	def self.enum_events # :nodoc
 	    @__enum_events__ ||= enum_for(:each_event)
 	end
 
+        # call-seq:
+        #   task.each_event { |event_object| ... } => task
+        #
         # Iterates on all the events defined for this task
-        def each_event # :yield:bound_event
+        #--
+        # The +only_wrapped+ flag is here for consistency with transaction
+        # proxies, and should probably not be used in user code.
+        def each_event(only_wrapped = true) # :yield:bound_event
 	    for _, ev in bound_events
 		yield(ev)
 	    end
+            self
         end
 	alias :each_plan_child :each_event
 
@@ -1271,8 +1594,34 @@ module Roby
         end
     
         # call-seq:
-        #   on(event_model) { |event| ... }
-        #   on(event_model => ev1, ev2 => [ ev3, ev4 ]) { |event| ... }
+        #   signal(name1 => name2, name3 => [name4, name5])
+        #
+        # Establish model-level signals between events of that task. These
+        # signals will be established on all the instances of this task model
+        # (and its subclasses).
+        def self.signal(mappings)
+            mappings.each do |from, to|
+                from    = event_model(from)
+                targets = Array[*to].map { |ev| event_model(ev) }
+
+                if from.terminal?
+                    non_terminal = targets.find_all { |ev| !ev.terminal? }
+                    if !non_terminal.empty?
+                        raise ArgumentError, "trying to establish a forwarding relation from the terminal event #{from} to the non-terminal events #{non_terminal}"
+                    end
+                end
+                non_controlable = targets.find_all { |ev| !ev.controlable? }
+                if !non_controlable.empty?
+                    raise ArgumentError, "trying to signal #{non_controlable.join(" ")} which is/are not controlable"
+                end
+
+                signal_sets[from.symbol].merge targets.map { |ev| ev.symbol }.to_value_set
+            end
+            update_terminal_flag
+        end
+
+        # call-seq:
+        #   on(event_name) { |event| ... }
         #
         # Adds an event handler for the given event model. When the event is fired,
         # all events given in argument will be called. If they are controlable,
@@ -1282,21 +1631,14 @@ module Roby
                 check_arity(user_handler, 1)
             end
 
+            if mappings.kind_of?(Hash)
+                Roby.warn_deprecated "the on(event => event) form of Task.on is deprecated. Use #signal to establish signals"
+                signal(mappings)
+            end
+
             mappings = [*mappings].zip([]) unless Hash === mappings
-            mappings.each do |from, to|
+            mappings.each do |from, _|
                 from = event_model(from).symbol
-                to = if to
-			 Array[*to].map do |ev| 
-			     model = event_model(ev)
-			     raise ArgumentError, "trying to signal #{ev} which is not controlable" unless model.controlable?
-			     model.symbol
-			 end
-                     else;  []
-                     end
-
-		signal_sets[from].merge to.to_value_set
-		update_terminal_flag
-
 		if user_handler 
 		    method_name = "event_handler_#{from}_#{Object.address_from_id(user_handler.object_id).to_s(16)}"
 		    define_method(method_name, &user_handler)
@@ -1329,8 +1671,17 @@ module Roby
         # See also Task#forward and EventGenerator#forward.
 	def self.forward(mappings)
             mappings.each do |from, to|
-                from = event_model(from).symbol
-		forwarding_sets[from].merge Array[*to].map { |ev| event_model(ev).symbol }.to_value_set
+                from    = event_model(from).symbol
+                targets = Array[*to].map { |ev| event_model(ev).symbol }
+
+                if event_model(from).terminal?
+                    non_terminal = targets.find_all { |name| !event_model(name).terminal? }
+                    if !non_terminal.empty?
+                        raise ArgumentError, "trying to establish a forwarding relation from the terminal event #{from} to the non-terminal event(s) #{targets}"
+                    end
+                end
+
+		forwarding_sets[from].merge targets.to_value_set
             end
 	    update_terminal_flag
 	end
@@ -1341,7 +1692,7 @@ module Roby
 	end
 
         def to_s # :nodoc:
-	    s = name.dup
+	    s = name.dup + arguments.to_s
 	    id = owners.map do |owner|
 		next if owner == Roby::Distributed
 		sibling = remote_siblings[owner]
@@ -1353,17 +1704,22 @@ module Roby
 	    s
 	end
 
-	def pretty_print(pp) # :nodoc:
-	    pp.text "#{self.class.name}:0x#{self.address.to_s(16)}"
-            pp.breakable
-	    pp.nest(2) do
-		pp.text "  owners: "
-		pp.seplist(owners) { |r| pp.text r.to_s }
+	def pretty_print(pp, with_owners = true) # :nodoc:
+	    pp.text "#{model.name}:0x#{self.address.to_s(16)}"
+            if with_owners
+                pp.breakable
+                pp.nest(2) do
+                    pp.text "  owners: "
+                    pp.seplist(owners) { |r| pp.text r.to_s }
+                    pp.breakable
 
-		pp.breakable
-		pp.text "arguments: "
-		arguments.pretty_print(pp)
-	    end
+                    pp.text "arguments: "
+                    arguments.pretty_print(pp)
+                end
+            else
+                pp.text " "
+                arguments.pretty_print(pp)
+            end
 	end
 
         # True if this task is a null task. See NullTask.
@@ -1417,7 +1773,7 @@ module Roby
 	def fullfills?(models, args = {})
 	    if models.kind_of?(Task)
 		klass, args = 
-		    models.class, 
+		    models.model, 
 		    models.meaningful_arguments
 		models = [klass]
 	    else
@@ -1429,7 +1785,7 @@ module Roby
 
 	    # Check the arguments that are required by the model
 	    for tag in models
-		unless self_model.has_ancestor?(tag)
+		if !self_model.has_ancestor?(tag)
 		    return false
 		end
 
@@ -1449,6 +1805,25 @@ module Roby
 	    true
 	end
 
+        # True if +self+ can be used to replace +target+
+        def can_replace?(target)
+            fullfills?(*target.fullfilled_model)
+        end
+
+	def can_merge?(target)
+	    target_model = target.fullfilled_model
+	    if !fullfills?(target_model.first)
+		return false
+	    end
+
+	    target_model.last.each do |key, val|
+		if arguments.has_key?(key) && arguments[key] != val
+		    return false
+		end
+	    end
+	    true
+	end
+
 	include ExceptionHandlingObject
 	inherited_enumerable('exception_handler', 'exception_handlers') { Array.new }
 
@@ -1457,9 +1832,10 @@ module Roby
 
 	@@exception_handler_id = 0
 
-	# call-seq:
-	#   on_exception(TaskModelViolation, ...) { |task, exception_object| ... }
-	#
+	##
+        # :call-seq:
+	#   on_exception(exception_class, ...) { |task, exception_object| ... }
+	# 
         # Defines an exception handler. matcher === exception_object is used to
         # determine if the handler should be called when +exception_object+ has
         # been fired. The first matching handler is called. Call #pass_exception to pass
@@ -1576,8 +1952,8 @@ module Roby
 	    singleton_class.class_eval do
 		setup_poll_method(block)
 	    end
-	    on(:start) { Control.event_processing << method(:poll) }
-	    on(:stop)  { Control.event_processing.delete(method(:poll)) }
+            on(:start) { |ev| @poll_handler_id = plan.engine.add_propagation_handler(method(:poll)) }
+            on(:stop)  { |ev| plan.engine.remove_propagation_handler(@poll_handler_id) }
 	end
     end
 
@@ -1617,7 +1993,7 @@ module Roby
 	    start_event.call
 	end
 	on :start do
-	    success_event.forward_once event(:success)
+	    success_event.forward_to_once event(:success)
 	    success_event.if_unreachable(true) do
 		emit :failed if executable?
 	    end
@@ -1648,5 +2024,3 @@ module Roby
 
 end
 
-require 'roby/task-operations'
-