roby 0.7

data/lib/roby/event.rb

@@ -0,0 +1,897 @@
+require 'roby/plan-object'
+require 'roby/exceptions'
+require 'set'
+
+module Roby
+    # Event objects are the objects representing a particular emission in the
+    # event propagation process. They represent the common propagation
+    # information (time, generator, sources, ...) and provide some common
+    # functionalities related to propagation as well.
+    class Event
+        # The generator which emitted this event
+	attr_reader :generator
+
+	def initialize(generator, propagation_id, context, time = Time.now)
+	    @generator, @propagation_id, @context, @time = generator, propagation_id, context.freeze, time
+	end
+
+	attr_accessor :propagation_id, :context, :time
+	attr_accessor :sources
+	protected :propagation_id=, :context=, :time=
+
+	# To be used in the event generators ::new methods, when we need to reemit
+	# an event while changing its 
+	def reemit(new_id, new_context = nil)
+	    if propagation_id != new_id || (new_context && new_context != context)
+		new_event = self.dup
+		new_event.propagation_id = new_id
+		new_event.context = new_context
+		new_event.time = Time.now
+		new_event
+	    else
+		self
+	    end
+	end
+
+	def name; model.name end
+	def model; self.class end
+	def inspect; "#<#{model.to_s}:0x#{address.to_s(16)} generator=#{generator} model=#{model}" end
+
+        # Returns an event generator which will be emitted once +time+ seconds
+        # after this event has been emitted.
+        def after(time)
+            State.at :t => (self.time + time)
+        end
+
+	def to_s
+	    "[#{time.to_hms} @#{propagation_id}] #{self.class.to_s}: #{context}"
+	end
+        def pretty_print(pp)
+            pp.text "[#{time.to_hms} @#{propagation_id}] #{self.class}"
+            if context
+                pp.breakable
+                pp.nest(2) do
+                    pp.text "  "
+                    pp.seplist(context) { |v| v.pretty_print(pp) }
+                end
+            end
+        end
+    end
+
+    # EventGenerator objects are the objects which manage the event generation
+    # process (propagation, event creation, ...). They can be combined
+    # logically using & and |.
+    #
+    # === Standard relations
+    # - signals: calls the *command* of an event when this generator emits
+    # - forwardings: *emits* another event when this generator emits
+    #
+    # === Hooks
+    # The following hooks are defined:
+    # * #postponed
+    # * #calling
+    # * #called
+    # * #fired
+    # * #signalling
+    # * #forwarding
+    #
+    class EventGenerator < PlanObject
+	attr_writer :executable
+
+	# True if this event is executable. A non-executable event cannot be
+	# called even if it is controlable
+	def executable?; @executable end
+
+	# Creates a new Event generator which is emitted as soon as one of this
+	# object and +generator+ is emitted
+	def |(generator)
+	    OrGenerator.new << self << generator
+	end
+
+	# Creates a AndGenerator object which is emitted when both this object
+	# and +generator+ are emitted
+	def &(generator)
+	    AndGenerator.new << self << generator
+	end
+
+	attr_enumerable(:handler, :handlers) { Array.new }
+
+	def initialize_copy(old) # :nodoc:
+	    super
+
+	    @history = old.history.dup
+	end
+
+	def model; self.class end
+	# The model name
+	def name; model.name end
+	# The count of command calls that have not a corresponding emission
+	attr_reader :pending
+	# True if this event has been called but is not emitted yet
+	def pending?; pending end
+
+	# call-seq:
+	#   EventGenerator.new
+	#   EventGenerator.new(false)
+	#   EventGenerator.new(true)
+	#   EventGenerator.new { |event| ... }
+	#
+	# Create a new event generator. If a block is given, the event is
+	# controlable and the block is its command. If a +true+ argument is
+	# given, the event is controlable and is 'pass-through': it is emitted
+	# as soon as its command is called. If no argument is given (or a
+	# +false+ argument), then it is not controlable
+	def initialize(command_object = nil, &command_block)
+	    @preconditions = []
+	    @handlers = []
+	    @pending  = false
+	    @unreachable = false
+	    @unreachable_handlers = []
+
+	    if command_object || command_block
+		self.command = if command_object.respond_to?(:call)
+				   command_object
+			       elsif command_block
+				   command_block
+			       else
+				   method(:default_command)
+			       end
+	    end
+	    super() if defined? super
+	    @executable = true
+	end
+
+	def default_command(context)
+	    emit(*context)
+	end
+
+	# The current command block
+	attr_accessor :command
+
+	# True if this event is controlable
+	def controlable?; !!@command end
+
+	# Returns true if the command has been called and false otherwise
+	# The command won't be called if #postpone() is called within the
+	# #calling hook
+	#
+	# This is used by propagation code, and should never be called directly
+	def call_without_propagation(context) # :nodoc:
+	    if !controlable?
+		raise EventNotControlable.new(self), "#call called on a non-controlable event"
+	    end
+
+	    postponed = catch :postponed do 
+		calling(context)
+		@pending = true
+
+		Propagation.propagation_context([self]) do
+		    command[context]
+		end
+
+		false
+	    end
+
+	    if postponed
+		@pending = false
+		postponed(context, *postponed)
+		false
+	    else
+		called(context)
+		true
+	    end
+
+	rescue Exception
+	    @pending = false
+	    raise
+	end
+
+	# Call the command associated with self. Note that an event might be
+	# non-controlable and respond to the :call message. Controlability must
+	# be checked using #controlable?
+	def call(*context)
+	    if !self_owned?
+		raise OwnershipError, "not owner"
+	    elsif !controlable?
+		raise EventNotControlable.new(self), "#call called on a non-controlable event"
+	    elsif !executable?
+		raise EventNotExecutable.new(self), "#call called on #{self} which is non-executable event"
+	    elsif !Roby.inside_control?
+		raise ThreadMismatch, "#call called while not in control thread"
+	    end
+
+	    context.compact!
+	    if Propagation.gathering?
+		Propagation.add_event_propagation(false, Propagation.sources, self, (context unless context.empty?), nil)
+	    else
+		errors = Propagation.propagate_events do |initial_set|
+		    Propagation.add_event_propagation(false, nil, self, (context unless context.empty?), nil)
+		end
+		if errors.size == 1
+		    e = errors.first.exception
+		    raise e, e.message, e.backtrace
+		elsif !errors.empty?
+		    for e in errors
+			STDERR.puts e.exception.full_message
+		    end
+		    raise "multiple exceptions"
+		end
+	    end
+	end
+
+	# Establishes signalling and/or event handlers from this event
+	# generator. 
+        #
+        # If +time+ is given it is either a :delay => time association, or a
+        # :at => time association. In the first case, +time+ is a floating-point
+        # delay in seconds and in the second case it is a Time object which is
+        # the absolute point in time at which this propagation must happen.
+	def on(signal = nil, time = nil, &handler)
+	    if signal
+		self.signal(signal, time)
+	    end
+
+	    if handler
+		check_arity(handler, 1)
+		self.handlers << handler
+	    end
+
+	    self
+	end
+
+	# Adds a signal from this event to +generator+. +generator+ must be
+	# controlable.
+        #
+        # If +time+ is given it is either a :delay => time association, or a
+        # :at => time association. In the first case, +time+ is a floating-point
+        # delay in seconds and in the second case it is a Time object which is
+        # the absolute point in time at which this propagation must happen.
+	def signal(generator, timespec = nil)
+	    if !generator.controlable?
+		raise EventNotControlable.new(self), "trying to establish a signal between #{self} and #{generator}"
+	    end
+	    timespec = Propagation.validate_timespec(timespec)
+
+	    add_signal generator, timespec
+	    self
+	end
+
+	# A set of blocks called when this event cannot be emitted again
+	attr_reader :unreachable_handlers
+
+	# Calls +block+ if it is impossible that this event is ever emitted
+	def if_unreachable(cancel_at_emission = false, &block)
+	    unreachable_handlers << [cancel_at_emission, block]
+	    block.object_id
+	end
+
+        # Returns an event which will be emitted when this event becones
+        # unreachable
+        def when_unreachable
+            # NOTE: the unreachable event is not directly tied to this one from
+            # a GC point of view (being able to do this would be useful, but
+            # anyway). So, it is possible that it is GCed because the event
+            # user did not take care to use it.
+            if !@unreachable_event || !@unreachable_event.plan
+                result = EventGenerator.new(true)
+                if_unreachable(false) do
+                    if result.plan
+                        result.emit
+                    end
+                end
+                add_causal_link result
+                @unreachable_event = result
+            end
+            @unreachable_event
+        end
+
+        # Emit +generator+ when +self+ is fired, without calling the command of
+        # +generator+, if any.
+        #
+        # If +timespec+ is given it is either a :delay => time association, or a
+        # :at => time association. In the first case, +time+ is a floating-point
+        # delay in seconds and in the second case it is a Time object which is
+        # the absolute point in time at which this propagation must happen.
+	def forward(generator, timespec = nil)
+	    timespec = Propagation.validate_timespec(timespec)
+	    add_forwarding generator, timespec
+	    self
+	end
+
+	# Returns an event which is emitted +seconds+ seconds after this one
+	def delay(seconds)
+	    if seconds == 0 then self
+	    else
+		ev = EventGenerator.new
+		forward(ev, :delay => seconds)
+		ev
+	    end
+	end
+
+	# Signal the +signal+ event the first time this event is emitted.  If
+	# +time+ is non-nil, delay the signalling this many seconds. 
+	def signal_once(signal, time = nil); once(signal, time) end
+
+	# Equivalent to #on, but call the handler and/or signal the target
+	# event only once.
+	def once(signal = nil, time = nil)
+	    handler = nil
+	    on(signal, time) do |context|
+		yield(context) if block_given?
+		self.handlers.delete(handler)
+		remove_signal(signal) if signal
+	    end
+	    handler = self.handlers.last
+	end
+
+	# Forwards to +ev+ only once
+	def forward_once(ev)
+	    forward(ev)
+	    once do
+		remove_forwarding ev
+	    end
+	end
+
+	def to_event; self end
+
+	# Returns the set of events directly related to this one
+	def related_events(result = nil); related_objects(nil, result) end
+	# Returns the set of tasks directly related to this event
+	def related_tasks(result = nil)
+	    result ||= ValueSet.new
+	    for ev in related_events
+		if ev.respond_to?(:task)
+		    result << ev.task
+		end
+	    end
+	    result
+	end
+
+	# Create a new event object for +context+
+	def new(context); Event.new(self, Propagation.propagation_id, context, Time.now) end
+
+	# Adds a propagation originating from this event to event propagation
+	def add_propagation(only_forward, event, signalled, context, timespec) # :nodoc:
+	    if self == signalled
+		raise PropagationError, "#{self} is trying to signal itself"
+	    elsif !only_forward && !signalled.controlable?
+		raise PropagationError, "trying to signal #{signalled} from #{self}"
+	    end
+
+	    Propagation.add_event_propagation(only_forward, [event], signalled, context, timespec)
+	end
+	private :add_propagation
+
+	# Do fire this event. It gathers the list of signals that are to
+	# be propagated in the next step and calls fired()
+	#
+	# This method is always called in a propagation context
+	def fire(event)
+	    Propagation.propagation_context([event]) do |result|
+		each_signal do |signalled|
+		    add_propagation(false, event, signalled, event.context, self[signalled, EventStructure::Signal])
+		end
+		each_forwarding do |signalled|
+		    add_propagation(true, event, signalled, event.context, self[signalled, EventStructure::Forwarding])
+		end
+
+		@happened = true
+		fired(event)
+
+		call_handlers(event)
+	    end
+	end
+
+	private :fire
+	
+	# Call the event handlers defined for this event generator
+	def call_handlers(event)
+	    # Since we are in a gathering context, call
+	    # to other objects are not done, but gathered in the 
+	    # :propagation TLS
+	    each_handler do |h| 
+		begin
+		    h.call(event)
+		rescue Exception => e
+		    Propagation.add_error( EventHandlerError.new(e, event) )
+		end
+	    end
+	end
+
+	# Raises an exception object when an event whose command has been
+	# called won't be emitted (ever)
+	def emit_failed(*what)
+	    what, message = *what
+	    what ||= EmissionFailed
+
+	    if !message && what.respond_to?(:to_str)
+		message = what.to_str
+		what = EmissionFailed
+	    end
+
+	    failure_message = "failed to emit #{self}: #{message}"
+	    error = if Class === what then what.new(nil, self)
+		    else what
+		    end
+	    error = error.exception failure_message
+
+	    Propagation.add_error(error)
+
+	ensure
+	    @pending = false
+	end
+
+	# Emits the event regardless of wether we are in a propagation context
+	# or not Returns true to match the behavior of
+	# #call_without_propagation
+	#
+	# This is used by event propagation. Do not call directly: use #call instead
+	def emit_without_propagation(context) # :nodoc:
+	    if !executable?
+		raise EventNotExecutable.new(self), "#emit called on #{self} which is not executable"
+	    end
+
+	    emitting(context)
+
+	    # Create the event object
+	    event = new(context)
+	    unless event.respond_to?(:context)
+		raise TypeError, "#{event} is not a valid event object in #{self}"
+	    end
+	    event.sources = Propagation.source_events
+	    fire(event)
+
+	    true
+
+	ensure
+	    @pending = false
+	end
+
+	# Emit the event with +context+ as the event context
+	def emit(*context)
+	    if !executable?
+		raise EventNotExecutable.new(self), "#emit called on #{self} which is not executable"
+	    elsif !self_owned?
+		raise OwnershipError, "cannot emit an event we don't own. #{self} is owned by #{owners}"
+	    elsif !Roby.inside_control?
+		raise ThreadMismatch, "#emit called while not in control thread"
+	    end
+
+	    context.compact!
+	    if Propagation.gathering?
+		Propagation.add_event_propagation(true, Propagation.sources, self, (context unless context.empty?), nil)
+	    else
+		errors = Propagation.propagate_events do |initial_set|
+		    Propagation.add_event_propagation(true, Propagation.sources, self, (context unless context.empty?), nil)
+		end
+		if errors.size == 1
+		    e = errors.first.exception
+		    raise e, e.message, e.backtrace
+		elsif !errors.empty?
+		    for e in errors
+			STDERR.puts e.full_message
+		    end
+		    raise "multiple exceptions"
+		end
+	    end
+	end
+
+	# Deprecated. Instead of using
+	#   dest.emit_on(source)
+	# now use
+	#   source.forward(dest)
+	def emit_on(generator, timespec = nil)
+	    generator.forward(self, timespec)
+	    self
+	end
+
+        # Sets up +ev+ and +self+ to represent that the command of +self+ is to
+        # be achieved by the emission of +ev+. It is to be used in a command
+        # handler:
+        #
+	#   event :start do |context|
+	#	init = <create an initialization event>
+	#	event(:start).achieve_with(init)
+	#   end
+        #
+        # If +ev+ becomes unreachable, an EmissionFailed exception will be
+        # raised. If a block is given, it is supposed to return the context of
+        # the event emitted by +self+, given the context of the event emitted
+        # by +ev+.
+        #
+        # From an event propagation point of view, it looks like:
+        # TODO: add a figure
+	def achieve_with(ev)
+	    stack = caller(1)
+	    if block_given?
+		ev.add_causal_link self
+		ev.once do |context|
+		    self.emit(yield(context))
+		end
+	    else
+		ev.forward_once self
+	    end
+
+	    ev.if_unreachable(true) do |reason|
+		msg = "#{ev} is unreachable#{ " (#{reason})" if reason }, in #{stack.first}"
+		if ev.respond_to?(:task)
+		    msg << "\n  " << ev.task.history.map { |ev| "#{ev.time.to_hms} #{ev.symbol}: #{ev.context}" }.join("\n  ")
+		end
+		emit_failed(UnreachableEvent.new(self, reason), msg)
+	    end
+	end
+	# For backwards compatibility. Use #achieve_with.
+	def realize_with(task); achieve_with(task) end
+
+	# A [time, event] array of past event emitted by this object
+	attribute(:history) { Array.new }
+	# True if this event has been emitted once.
+	attr_predicate :happened
+	# Last event to have been emitted by this generator
+	def last; history.last end
+
+        # Defines a precondition handler for this event. Precondition handlers
+        # are blocks which are called just before the event command is called.
+        # If the handler returns false, the calling is aborted by a
+        # PreconditionFailed exception
+	def precondition(reason = nil, &block)
+	    @preconditions << [reason, block]
+	end
+
+	# Yields all precondition handlers defined for this generator
+	def each_precondition # :yield:reason, block
+	    @preconditions.each { |o| yield(o) } 
+	end
+
+	# Call #postpone in #calling to announce that the event should not be
+	# called now, but should be called back when +generator+ is emitted
+	#
+	# A reason string can be provided for debugging purposes
+	def postpone(generator, reason = nil)
+	    generator.on self
+	    yield if block_given?
+	    throw :postponed, [generator, reason]
+	end
+
+	# Hook called when the event has been postponed. See #postpone
+	def postponed(context, generator, reason); super if defined? super end	
+
+	# Call this method in the #calling hook to cancel calling the event
+	# command. This raises an EventCanceled exception with +reason+ for
+	# message
+	def cancel(reason = nil)
+	    raise EventCanceled.new(self), (reason || "event canceled")
+	end
+
+	# Hook called when this event generator is called (i.e. the associated
+	# command is), before the command is actually called. Think of it as a
+	# pre-call hook.
+	#
+	# The #postpone method can be called in this hook
+	def calling(context)
+	    super if defined? super 
+	    each_precondition do |reason, block|
+		result = begin
+			     block.call(self, context)
+			 rescue EventPreconditionFailed => e
+			     e.generator = self
+			     raise
+			 end
+
+		if !result
+		    raise EventPreconditionFailed.new(self), "precondition #{reason} failed"
+		end
+	    end
+	end
+
+	# Hook called just after the event command has been called
+	def called(context); super if defined? super end
+
+	# Hook called when this generator has been fired. +event+ is the Event object
+	# which has been created.
+	def fired(event)
+	    unreachable_handlers.delete_if { |cancel, _| cancel }
+
+	    history << event
+	    if EventGenerator.event_gathering.has_key?(event.generator)
+		for c in EventGenerator.event_gathering[event.generator]
+		    c << event
+		end
+	    end
+
+	    super if defined? super
+	end
+
+	# Hook called just before the +to+ generator is signalled by this
+	# generator. +event+ is the Event object which has been generated by
+	# this model
+	def signalling(event, to); super if defined? super end
+	
+	# Hook called just before the propagation forwards +self+ to +to+.
+	# +event+ is the Event object which has been generated by this model
+	def forwarding(event, to); super if defined? super end
+	
+	# Hook called when this event will be emitted
+	def emitting(context); super if defined? super end
+
+	# call-seq:
+	#   filter(new_context) => filtering_event
+	#   filter { |context| ... } => filtering_event
+	#
+	# Returns an event generator which forwards the events fired by this
+	# one, but by changing the context. In the first form, the new context
+	# is set to +new_context+.  In the second form, to the value returned
+	# by the given block
+	def filter(*new_context, &block)
+	    filter = FilterGenerator.new(new_context, &block)
+	    self.on(filter)
+	    filter
+	end
+
+	# Returns a new event generator which emits until the +limit+ event is
+	# sent
+	#
+	#   source, ev, limit = (1..3).map { EventGenerator.new(true) }
+	#   ev.until(limit).on { STDERR.puts "FIRED !!!" }
+	#   source.on ev
+	#
+	# Will do
+	#
+	#   source.call # => FIRED !!!
+	#   limit.emit
+	#   source.call # => 
+	#
+	# See also UntilGenerator
+	def until(limit); UntilGenerator.new(self, limit) end
+	
+	# Checks that ownership allows to add the self => child relation
+	def add_child_object(child, type, info) # :nodoc:
+	    unless child.read_write?
+		raise OwnershipError, "cannot add an event relation on a child we don't own. #{child} is owned by #{child.owners.to_a} (plan is owned by #{plan.owners.to_a if plan})"
+	    end
+
+	    super
+	end
+
+	@@event_gathering = Hash.new { |h, k| h[k] = ValueSet.new }
+	# If a generator in +events+ fires, add the fired event in +collection+
+	def self.gather_events(collection, events)
+	    for ev in events
+		event_gathering[ev] << collection
+	    end
+	end
+	# Remove the notifications that have been registered for +collection+
+	def self.remove_event_gathering(collection)
+	    @@event_gathering.delete_if do |_, collections| 
+		collections.delete(collection)
+		collections.empty?
+	    end
+	end
+	# An array of [collection, events] elements, collection being the
+	# object in which we must add the fired events, and events the set of
+	# event generators +collection+ is listening for.
+	def self.event_gathering; @@event_gathering end
+
+	# This module is hooked in Roby::Plan to remove from the
+	# event_gathering sets the events that have been finalized
+	module FinalizedEventHook
+	    def finalized_event(event)
+		super if defined? super
+		event.unreachable!
+	    end
+	end
+	Roby::Plan.include FinalizedEventHook
+
+	attr_predicate :unreachable?
+
+	# Called internally when the event becomes unreachable
+	def unreachable!(reason = nil)
+	    return if @unreachable
+	    @unreachable = true
+
+	    unreachable_handlers.each do |_, block|
+		begin
+		    block.call(reason)
+		rescue Exception => e
+		    Propagation.add_error(EventHandlerError.new(e, self))
+		end
+	    end
+	    unreachable_handlers.clear
+	end
+
+	def pretty_print(pp) # :nodoc:
+	    pp.text to_s
+	    pp.group(2, ' {', '}') do
+		pp.breakable
+		pp.text "owners: "
+		pp.seplist(owners) { |r| pp.text r.to_s }
+
+		pp.breakable
+		pp.text "relations: "
+		pp.seplist(relations) { |r| pp.text r.name }
+	    end
+	end
+    end
+
+
+    # This generator reemits an event after having changed its context. See
+    # EventGenerator#filter for a more complete explanation
+    class FilterGenerator < EventGenerator
+	def initialize(user_context, &block)
+	    if block && !user_context.empty?
+		raise ArgumentError, "you must set either the filter or the value, not both"
+	    end
+
+	    if block
+		super() do |context| 
+		    context = context.map do |val|
+			block.call(val)
+		    end
+		    emit(*context)
+		end
+	    else
+		super() do 
+		    emit(*user_context)
+		end
+	    end
+	end
+    end
+
+    # Event generator which fires when all its source events have fired
+    # See EventGenerator#& for a more complete description
+    class AndGenerator < EventGenerator
+	def initialize
+	    super do |context|
+		emit_if_achieved(context)
+	    end
+
+	    # This hash is a event_generator => event mapping of the last
+	    # events of each event generator. We compare the event stored in
+	    # this hash with the last events of each source to know if the
+	    # source fired since it has been added to this AndGenerator
+	    @events = Hash.new
+
+	    # This flag is true unless we are not waiting for the emission
+	    # anymore.
+	    @active = true
+	end
+
+	# Resets the waiting. If the event has already been emitted, it re-arms
+	# it.
+	def reset
+	    @active = true
+	    each_parent_object(EventStructure::Signal) do |source|
+		@events[source] = source.last
+		if source.respond_to?(:reset)
+		    source.reset
+		end
+	    end
+	end
+
+	def emit_if_achieved(context) # :nodoc:
+	    return unless @active
+	    each_parent_object(EventStructure::Signal) do |source|
+		return if @events[source] == source.last
+	    end
+	    @active = false
+	    emit(nil)
+	end
+
+	def empty?; events.empty? end
+	
+	# Adds a new source to +events+ when a source event is added
+	def added_parent_object(parent, relations, info) # :nodoc:
+	    super if defined? super
+	    return unless relations.include?(EventStructure::Signal)
+	    @events[parent] = parent.last
+
+	    # If the parent is unreachable, check that it has neither been
+	    # removed, nor it has been emitted
+	    parent.if_unreachable(true) do |reason|
+		if @events[parent] == parent.last
+		    unreachable!(reason || parent)
+		end
+	    end
+	end
+
+	# Removes a source from +events+ when the source is removed
+	def removed_parent_object(parent, relations) # :nodoc:
+	    super if defined? super
+	    return unless relations.include?(EventStructure::Signal)
+	    @events.delete(parent)
+	end
+
+	# The set of source events
+	def events;  parent_objects(EventStructure::Signal) end
+	# The set of events which we are waiting for
+	def waiting; parent_objects(EventStructure::Signal).find_all { |ev| @events[ev] == ev.last } end
+	
+	# Add a new source to this generator
+	def << (generator)
+	    generator.add_signal self
+	    self
+	end
+    end
+
+    # Event generator which fires when the first of its source events fires.
+    # All event generators which signal this one are considered as sources.
+    #
+    # See also EventGenerator#| and #<<
+    class OrGenerator < EventGenerator
+        # Creates a new OrGenerator without any sources.
+	def initialize
+	    super do |context|
+		emit_if_first(context)
+	    end
+	    @active = true
+	end
+
+        # True if there is no source event for this combinator.
+	def empty?; parent_objects(EventStructure::Signal).empty? end
+
+        # Reset its state, so as to behave as if no source has ever
+        # been emitted.
+	def reset
+	    @active = true
+	    each_parent_object(EventStructure::Signal) do |source|
+		if source.respond_to?(:reset)
+		    source.reset
+		end
+	    end
+	end
+
+	def emit_if_first(context) # :nodoc:
+	    return unless @active
+	    @active = false
+	    emit(context)
+	end
+
+	def added_parent_object(parent, relations, info) # :nodoc:
+	    super if defined? super
+	    return unless relations.include?(EventStructure::Signal)
+
+	    parent.if_unreachable(true) do |reason|
+		if !happened? && parent_objects(EventStructure::Signal).all? { |ev| ev.unreachable? }
+		    unreachable!(reason || parent)
+		end
+	    end
+	end
+
+	# Adds +generator+ to the sources of this event
+	def << (generator)
+	    generator.add_signal self
+	    self
+	end
+    end
+
+    # This event generator combines a source and a limit in a temporal pattern.
+    # The generator acts as a pass-through for the source, until the limit is
+    # itself emitted. It means that:
+    #
+    # * before the limit is emitted, the generator will emit each time its
+    #  source emits 
+    # * since the point where the limit is emitted, the generator
+    #   does not emit anymore
+    #
+    # See also EventGenerator#until
+    class UntilGenerator < Roby::EventGenerator
+        # Creates a until generator for the given source and limit event
+        # generators
+	def initialize(source = nil, limit = nil)
+	    super() do |context|
+		plan.remove_object(self) if plan 
+		clear_relations
+	    end
+
+	    if source && limit
+		source.forward(self)
+		limit.signal(self)
+	    end
+	end
+    end
+
+    unless defined? EventStructure
+	EventStructure = RelationSpace(EventGenerator)
+    end
+end
+