Module: Roby::ExecutionEngine::PropagationHandlerMethods Private

Included in:
Roby::ExecutionEngine, Roby::ExecutionEngine
Defined in:
lib/roby/execution_engine.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#external_events_handlers ⇒ Array<PollBlockDefinition> (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Code blocks that get called at the beginning of each cycle

Returns:



273
274
275
 
# File 'lib/roby/execution_engine.rb', line 273

def external_events_handlers
  @external_events_handlers
end

#propagation_handlers ⇒ Array<PollBlockDefinition> (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Returns:



278
279
280
 
# File 'lib/roby/execution_engine.rb', line 278

def propagation_handlers
  @propagation_handlers
end

#side_work_handlers ⇒ Array<PollBlockDefinition> (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Code blocks that get called at the very end of the execution cycle, outside propagation context

Returns:



283
284
285
 
# File 'lib/roby/execution_engine.rb', line 283

def side_work_handlers
  @side_work_handlers
end

Instance Method Details

#add_propagation_handler(type: :external_events, description: "propagation handler", **poll_options, &block) ⇒ #dispose

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Parameters:

  • type (:propagation, :external_events) (defaults to: :external_events) —

    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

  • options (Hash) —

    a customizable set of options

Returns:

  • (#dispose) —

    an object whose #dispose method deregisters the handler



335
336
337
338
339
340
341
342
343
344
 
# File 'lib/roby/execution_engine.rb', line 335

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)
    case type
    when :propagation
        propagation_handlers << handler
    when :external_events
        external_events_handlers << handler
    end
    handler
end

#add_side_work_handler(description: "side work handler", **poll_options, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Execute the given block at the end of a cycle, just before sleeping until the beginning of the next cycle.

The blocks are NOT called in propagation context, do NOT do anything event-related in there

Returns:



381
382
383
384
385
386
387
 
# File 'lib/roby/execution_engine.rb', line 381

def add_side_work_handler(description: "side work handler", **poll_options, &block)
    # Reuse the propagation handler stuff, even if it's a bit
    # overkill
    handler = PollBlockDefinition.new(description, block, **poll_options)
    side_work_handlers << handler
    handler.id
end

#at_cycle_begin(description: "at_cycle_begin", **options, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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



360
361
362
 
# File 'lib/roby/execution_engine.rb', line 360

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

  • type (:external_events, :propagation) (defaults to: :external_events) —

    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.

  • description (String) (defaults to: "propagation handler") —

    a string describing the block. It will be used when adding timepoints to the event log



297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/roby/execution_engine.rb', line 297

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
    [type, handler]
end

#each_cycle(description: "each_cycle", &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Returns:



369
370
371
 
# File 'lib/roby/execution_engine.rb', line 369

def each_cycle(description: "each_cycle", &block)
    add_propagation_handler(description: description, &block)
end

#remove_propagation_handler(id) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:



351
352
353
354
355
356
357
 
# File 'lib/roby/execution_engine.rb', line 351

def remove_propagation_handler(id)
    # Some code relied on remove_propagation_handler being a no-op
    # if id is nil. Keep this, especially since
    # remove_propagation_handler will in-fine completely be removed
    id&.dispose
    nil
end

#remove_side_work_handler(handler_id) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Remove a handler registered with #add_side_work_handler

Parameters:



393
394
395
396
 
# File 'lib/roby/execution_engine.rb', line 393

def remove_side_work_handler(handler_id)
    side_work_handlers.delete_if { |p| p.id == handler_id }
    nil
end