Function rclc_executor_init

Function Documentation

rcl_ret_t rclc_executor_init(rclc_executor_t *executor, rcl_context_t *context, const size_t number_of_handles, const rcl_allocator_t *allocator)

Initializes an executor. It creates a dynamic array with size number_of_handles using the allocator. As the Executor is intended for embedded controllers, dynamic memory management is crucial. Therefore at initialization of the RCLC-Executor, the user defines the total number_of_handles. A handle is a term for subscriptions, timers, services, clients and guard conditions. The heap will be allocated only in this phase and no more memory will be allocated in the running phase in the executor.

Also in the XRCE-DDS middleware the maximum number are configured. See Memory Management Tutorial for the default values. If you need larger values, you need to update your colcon.meta configuration file and rebuild. To make sure that the changes were applied, you can check the defined values in the following library include file: build/rmw_microxrcedds/include/rmw_microxrcedds_c/config.h

The heap memory of corresponding wait-set is allocated in the first iteration of a spin-method, which calls internally rclc_executor_prepare. Optionally, you can also call rclc_executor_prepare before calling any of the spin-methods. Then all wait-set related memory allocation will be done in rclc_executor_prepare and not in the first iteration of the spin-method.

This makes this Executor static in terms of memory allocation, in the sense, that during runtime no heap allocations occur. You can add, however, at runtime as many handles, e.g. subscriptions, to the executor until the maximum number of handles is reached. In this case, the wait-set needs to be updated and rclc_executor_prepare is called again (with dynamic memory allocation in RCL).

  • Attribute

    Adherence

    Allocates Memory

    Yes

    Thread-Safe

    No

    Uses Atomics

    No

    Lock-Free

    Yes

Parameters:

  • executor – [inout] preallocated rclc_executor_t

  • context – [in] RCL context

  • number_of_handles – [in] is the total number of subscriptions, timers, services, clients and guard conditions. Do not include the number of nodes and publishers.

  • allocator – [in] allocator for allocating memory

Returns:

RCL_RET_OK if the executor was initialized successfully

Returns:

RCL_RET_INVALID_ARGUMENT if any null pointer as argument

Returns:

RCL_RET_ERROR in case of failure