From 6ae73ca28e003c547746ad33f30d170625e362ce Mon Sep 17 00:00:00 2001 From: Jan Staschulat Date: Sat, 17 Jul 2021 09:16:19 +0200 Subject: [PATCH] Feature/updated documentation executor (#117) * updated documentation for number_of_handles in rclc_executor_init function. To clarify that you can add subscriptions at runtime. Signed-off-by: Jan Staschulat * updated header documentation Signed-off-by: Jan Staschulat * Update rclc/README.md Co-authored-by: Pablo Garrido * Added documentation for rclc_executor_prepare. Signed-off-by: Jan Staschulat Co-authored-by: Pablo Garrido --- rclc/README.md | 5 ++--- rclc/include/rclc/executor.h | 15 +++++++++++++++ 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/rclc/README.md b/rclc/README.md index f200e5f4..df810fa7 100644 --- a/rclc/README.md +++ b/rclc/README.md @@ -273,9 +273,8 @@ Returns a zero initialized executor object. **rclc_executor_init(rclc_executor_t * executor, rcl_context_t * context, const size_t number_of_handles, const rcl_allocator_t * 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 `number_of_handles`. -The necessary dynamic memory will be allocated only in this phase and no more memory in the running phase. -This makes this Executor static in the sense, that during runtime no additional callbacks can be added. +Therefore at initialization of the RCLC-Executor, the user defines the total number of handles `number_of_handles`. A handle is a term for subscriptions, timers, services, clients and guard conditions. The necessary dynamic memory will be allocated only in this phase and no more memory in the running phase. The corresponding wait-set is allocated in the first execution of the spin-method or in the optional call to `rclc_executor_prepare` . +This makes this Executor static 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. The `context` is the RCL context, and `allocator` points to a memory allocator. **rclc_executor_set_timeout(rclc_executor_t * executor, const uint64_t timeout_ns)** diff --git a/rclc/include/rclc/executor.h b/rclc/include/rclc/executor.h index b78e33b5..4dda219e 100644 --- a/rclc/include/rclc/executor.h +++ b/rclc/include/rclc/executor.h @@ -94,6 +94,21 @@ rclc_executor_get_zero_initialized_executor(void); * Initializes an executor. * It creates a dynamic array with size \p number_of_handles using the * \p 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 \p 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. However, 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). * * * *