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 <[email protected]> * updated header documentation Signed-off-by: Jan Staschulat <[email protected]> * Update rclc/README.md Co-authored-by: Pablo Garrido <[email protected]> * Added documentation for rclc_executor_prepare. Signed-off-by: Jan Staschulat <[email protected]> Co-authored-by: Pablo Garrido <[email protected]>
ros2 · Jul 17, 2021 · 6ae73ca · 6ae73ca
1 parent a634f88
commit 6ae73ca
Show file tree

Hide file tree

Showing 2 changed files with 17 additions and 3 deletions.
diff --git 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
@@ -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).
  *
  *
  *  * <hr>