module Roby::ExecutionEngine::PropagationHandlerMethods

Add/remove propagation handler methods that are shared between the instance and the class

Attributes

external_events_handlers[R]

Code blocks that get called at the beginning of each cycle

@return [Array<PollBlockDefinition>]

propagation_handlers[R]

Code blocks that get called during propagation to handle some internal propagation mechanism

@return [Array<PollBlockDefinition>]

Public Instance Methods

add_propagation_handler(type: :external_events, description: 'propagation handler', **poll_options, &block) click to toggle source

The propagation handlers are blocks that should be called at various places during propagation for all plans. These objects are called in propagation context, which means that the events they would call or emit are injected in the propagation process itself.

@param [:propagation,:external_events] type defines when this block should be called. If

:external_events, it is called only once at the beginning of each
execution cycle. If :propagation, it is called once at the
beginning of each cycle, as well as after each propagation step.
The :late option also gives some control over when the handler is
called when in propagation mode

@option options [Boolean] once (false) if true, this handler will

be removed just after its first execution

@option options [Boolean] late (false) if true, the handler is

called only when there are no events to propagate anymore.

@option options [:raise,:ignore,:disable] on_error (:raise)

controls what happens when the block raises an exception. If
:raise, the error is registered as a framework error. If
:ignore, it is completely ignored. If :disable, the handler
will be disabled, i.e. not called anymore until #disabled?

@return [Object] an ID object that can be passed to

{#remove_propagation_handler}
# File lib/roby/execution_engine.rb, line 316
def add_propagation_handler(type: :external_events, description: 'propagation handler', **poll_options, &block)
    type, handler = create_propagation_handler(type: type, description: description, **poll_options, &block)
    if type == :propagation
        propagation_handlers << handler
    elsif type == :external_events
        external_events_handlers << handler
    end
    handler.id
end
at_cycle_begin(description: 'at_cycle_begin', **options, &block) click to toggle source

Add a handler that is called at the beginning of the execution cycle

# File lib/roby/execution_engine.rb, line 338
def at_cycle_begin(description: 'at_cycle_begin', **options, &block)
    add_propagation_handler(description: description, type: :external_events, **options, &block)
end
create_propagation_handler(type: :external_events, description: 'propagation handler', **poll_options, &block) click to toggle source

@api private

Helper method that gets the arguments necessary top create a propagation handler, sanitizes and normalizes them, and returns both the propagation type and the {PollBlockDefinition} object

@param [:external_events,:propagation] type whether the block should be registered as an

:external_events block, processed at the beginning of the cycle,
or a :propagation block, processed at each propagation loop.

@param [String] description a string describing the block. It will

be used when adding timepoints to the event log

@param poll_options (see PollBlockDefinition#initialize)

# File lib/roby/execution_engine.rb, line 278
def create_propagation_handler(type: :external_events, description: 'propagation handler', **poll_options, &block)
    check_arity block, 1
    handler = PollBlockDefinition.new(description, block, **poll_options)

    if type == :external_events
        if handler.late?
            raise ArgumentError, "only :propagation handlers can be marked as 'late', the external event handlers cannot"
        end
    elsif type != :propagation
        raise ArgumentError, "invalid value for the :type option. Expected :propagation or :external_events, got #{type}"
    end
    return type, handler
end
each_cycle(description: 'each_cycle', &block) click to toggle source

Execute the given block at the beginning of each cycle, in propagation context.

@return [Object] an ID that can be used to remove the handler using

{#remove_propagation_handler}
# File lib/roby/execution_engine.rb, line 347
def each_cycle(description: 'each_cycle', &block)
    add_propagation_handler(description: description, &block)
end
remove_propagation_handler(id) click to toggle source

This method removes a propagation handler which has been added by {#add_propagation_handler}.

@param [Object] id the block ID as returned by

{#add_propagation_handler}
# File lib/roby/execution_engine.rb, line 331
def remove_propagation_handler(id)
    propagation_handlers.delete_if { |p| p.id == id }
    external_events_handlers.delete_if { |p| p.id == id }
    nil
end