Skip to content

Commit df38aba

Browse files
committed
updated comments from review
Signed-off-by: Staschulat Jan (CR/AEX3) <jan.staschulat@de.bosch.com>
1 parent d7ee6a4 commit df38aba

1 file changed

Lines changed: 43 additions & 37 deletions

File tree

  • _docs/concepts/client_library/real-time_executor

‎_docs/concepts/client_library/real-time_executor/index.md‎

Lines changed: 43 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,9 @@ permalink: /docs/concepts/client_library/real-time_executor/
1010
* [Introduction](#introduction)
1111
* [ROS 2 Executor Concept](#ros-2-executor-concept)
1212
* [RCL Executor](#rcl-executor)
13-
* [API Layers](#api-layers)
1413
* [Concept](#concept)
15-
* [API](#api)
16-
* [Tutorial and Download](#tutorial-and-download)
14+
* [Example](#example)
15+
* [Download](#download)
1716
* [Background](#background)
1817
* [ROS 2 rclcpp Executor](#ros-2-rclcpp-executor)
1918
* [Complex semantics of the ROS 2 Executor](#complex-semantics-of-the-ros-2-executor)
@@ -58,58 +57,65 @@ The dispatching mechanism resembles the ROS 1 spin thread behavior: the Executor
5857

5958
See also section [ROS 2 rclcpp Executor](#ROS-2-rclcpp-Executor) for a more detailed functional desciption and an analysis of its semantics in section [Complex semantic of the ROS 2 Executor](#Complex-semantic-of-the-ROS-2-Executor).
6059

61-
## RCL-Executor
62-
This section describes a let-executor. It is a first step towards deterministic execution by providing static order scheduling with a let semantics. The abbreviation let stands for Logical-Execution-Time (let) and is a well-known concept in automotive domain to simplify synchronization in process scheduling. If refers to the concept to schedule multiple ready tasks in such a way, that first all input data is read for all tasks, and then all tasks are executed. This removes any inter-dependence of input data among these ready tasks and hence input data synchronization is improved.
60+
## RCL-LET-Executor
61+
This section describes the RCL-LET-executor. It is a first step towards deterministic execution by providing static order scheduling with a LET semantics. The abbreviation let stands for Logical-Execution-Time (LET) and is a well-known concept in automotive domain to simplify synchronization in process scheduling. If refers to the concept to schedule multiple ready tasks in such a way, that first all input data is read for all tasks, and then all tasks are executed. This removes any inter-dependence of input data among these ready tasks and hence input data synchronization is improved.
6362

6463
In the future, we plan to provide other executors with different deterministic semantics.
6564

66-
### API Layers
67-
As mentioned in the section [Introduction to Client Library](../), we plan to provide micro-ROS support for the C++ API and for the C API. The Real-Time Executor enriches the C API based on the ROS Client Library (rcl).
6865

6966
### Concept
7067
The let-executor implements a static order scheduler with logical-execution-time(let) semantics [[BP2017](#BP2017)] [[EK2018](#EK2018)]. During configuration the execution order of callbacks is defined and at runtime the callbacks are always processed in this order. The let-semantic refers to reading first all input data from the DDS-queue for all callbacks, storing the received messages or storing the event that a timer is ready. Then, in a second step, all callbacks, timers and the corresponding functions are executed in order as they were defined during configuration phase.
7168

72-
### API
69+
### Example
7370

74-
The API of the let-executor provides functions for configuration, defining the execution order of callbacks, running the scheduler and cleaning-up:
71+
We provide an example, who to use the RCL-LET-executor. First, the callbacks for the subscription and timer need to be defined. Then the ROS context and the ROS node are defined as well as the subscription and timer.
7572

76-
**Configuration**
77-
- rcle_let_executor_init(...)
78-
- rcle_let_executor_set_timeout(..)
73+
The executor is initialized with two handles. Then follow the _add_ functions, which define the static execution order of the handles. In this example, the subscription is always processed before the timer. Finally the executor is started with the _spin\_period_ function, which is continuously called every 20 ms.
74+
```C
75+
#include "rcl_executor/let_executor.h"
7976
80-
**Definition of the execution order**
81-
- rcle_let_executor_add_subscription(...)
82-
- rcle_let_executor_add_timer(...)
77+
// define subscription callback
78+
void my_sub_cb(const void * msgin)
79+
{
80+
// ...
81+
}
8382
84-
**Running the executor**
85-
- rcle_let_executor_spin_some(...)
86-
- rcle_let_executor_spin_period(...)
87-
- rcle_let_executor_spin(...)
83+
// define timer callback
84+
void my_timer_cb(rcl_timer_t * timer, int64_t last_call_time)
85+
{
86+
// ...
87+
}
8888
89-
**Clean-up memory**
90-
- rcle_let_executor_fini(...)
89+
// necessary ROS 2 objects
90+
rcl_context_t context;
91+
rcl_node_t node;
92+
rcl_subscription_t sub;
93+
rcl_timer_t timer;
94+
rcle_let_executor_t exe;
9195
96+
// define ROS context
97+
context = rcl_get_zero_initialized_context();
98+
// initialize ROS node
99+
rcl_node_init(&node, &context,...);
92100
93-
In the function `rcle_let_executor_init`, the user must specify the total number of handles to be executed. The term handle denotes the object to be executed, for example a timer or a subscription.
101+
// create a subscription
102+
rcl_subscription_init(&sub, &node, ...);
94103
95-
The function `rcle_let_executor_set_timeout` is an optional configuration function, which defines the timeout in nanoseconds for calling rcl_wait(), i.e. the time to wait for new data from the DDS queue each time spin_some() is executed. The default timeout is 100ms.
104+
// create a timer
105+
rcl_timer_init(&timer, &my_timer_cb, ... );
96106
97-
The functions `rcle_let_executor_add_subscription` and `rcle_let_executor_add_timer` add the corresponding handle to the executor. The maximum number of handles is defined in `rcle_let_executor_init` and must not be exceeded. The sequential order of these function calls defines the static execution order later at runtime.
107+
// initialize executor with two handles
108+
rcle_let_executor_init(&exe, &context, 2, ...);
98109
99-
The function `rcle_let_executor_spin_some` checks for new data from the DDS queue once. It first saves all incoming messages and, in a second step, executes all handles according the configured order. This implements the let semantics.
110+
// define static execution order of handles
111+
rcle_let_executor_add_subscription(&exe, &sub, &my_sub_cb, ...);
112+
rcle_let_executor_add_timer(&exe, &timer);
100113
101-
The function `rcle_let_executor_spin_period` calls `rcle_let_executor_spin_some` periodically (as defined with the argument period) as long as the ROS system is alive.
102-
103-
The function `rcle_let_executor_spin` calls `rcle_let_executor_spin_some` indefinitely as long as the ROS system is alive. Note, that this function call might create a high performance load on your processor.
104-
105-
The function `rlce_executor_fini` frees the dynamically allocated memory of the executor.
106-
107-
108-
As resources are very constrained on micro-controllers, specific attention has been paid to the memory allocation: Dynamic memory is only allocated during the initialization phase to reserve memory for all handles. This is the reason, why the total number of handles must be configured first. At runtime no memory is allocated by the let-executor.
109-
110-
### Tutorial and Download
111-
112-
The let-executor can be downloaded from the micro-ROS GitHub [rcl_executor repository](https://github.com/micro-ROS/rcl_executor). The package [rcl_executor](https://github.com/micro-ROS/rcl_executor/tree/dashing/rcl_executor) provides the let-executor library with a step-by-step tutorial and the package [rcl_executor_examples](https://github.com/micro-ROS/rcl_executor/tree/dashing/rcl_executor_examples) provides an example, how to use the let-executor.
114+
// spin with a period of 20ms
115+
rcle_let_executor_spin_period(&exe, 20);
116+
```
117+
### Download
118+
The LET-executor can be downloaded from the micro-ROS GitHub [rcl_executor repository](https://github.com/micro-ROS/rcl_executor). The package [rcl_executor](https://github.com/micro-ROS/rcl_executor/tree/dashing/rcl_executor) provides the let-executor library with a step-by-step tutorial and the package [rcl_executor_examples](https://github.com/micro-ROS/rcl_executor/tree/dashing/rcl_executor_examples) provides an example, how to use the let-executor.
113119

114120
## Background
115121

0 commit comments

Comments
 (0)