rcl_lifecycle  master
C API providing common functionality for ROS lifecycle.
All Classes Namespaces Files Functions Variables Modules Pages
transition_map.h
1 // Copyright 2016 Open Source Robotics Foundation, Inc.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 
16 #ifndef RCL_LIFECYCLE__TRANSITION_MAP_H_
17 #define RCL_LIFECYCLE__TRANSITION_MAP_H_
18 
19 #include "rcl/macros.h"
20 
21 #include "rcl_lifecycle/data_types.h"
22 
23 #ifdef __cplusplus
24 extern "C"
25 {
26 #endif
27 
29 /*
30  * Should be called to get a null rcl_lifecycle_transition_map_t before passing to
31  * rcl_lifecycle_register_state() or rcl_lifecycle_register_transition().
32  *
33  * \return rcl_lifecycle_transition_map_t a initilized struct
34  */
35 RCL_LIFECYCLE_PUBLIC
36 RCL_WARN_UNUSED
38 rcl_lifecycle_get_zero_initialized_transition_map();
39 
41 /*
42  * The function checks if the transition map is initialized. It returns `RCL_RET_OK`
43  * if the transition map is initialized successfully or `RCL_RET_ERROR` if the transition
44  * map is not initialized.
45  *
46  * <hr>
47  * Attribute | Adherence
48  * ------------------ | -------------
49  * Allocates Memory | No
50  * Thread-Safe | No
51  * Uses Atomics | No
52  * Lock-Free | Yes
53  *
54  * \param[in] transition_map pointer to the transition map struct to check
55  * \return `RCL_RET_OK` if the transition map is initialized successfully, or
56  * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or
57  * \return `RCL_RET_ERROR` if the transition map is not initialized.
58  */
59 RCL_LIFECYCLE_PUBLIC
60 RCL_WARN_UNUSED
62 rcl_lifecycle_transition_map_is_initialized(
63  const rcl_lifecycle_transition_map_t * transition_map);
64 
66 /*
67  * Calling this will set the rcl_lifecycle_transition_map_t struct into the an unitialized state that is
68  * functionally the same as before rcl_lifecycle_register_state or
69  * rcl_lifecycle_register_transition was called. This function make the rcl_lifecycle_transition_map_t invalid.
70  *
71  * <hr>
72  * Attribute | Adherence
73  * ------------------ | -------------
74  * Allocates Memory | Yes
75  * Thread-Safe | No
76  * Uses Atomics | No
77  * Lock-Free | Yes
78  *
79  * \param[inout] transition_map struct to be deinitialized
80  * \param[in] allocator a valid allocator used to deinitialized the state machine
81  * \return `RCL_RET_OK` if the state was deinitialized successfully, or
82  * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or
83  * \return `RCL_RET_ERROR` if an unspecified error occurs.
84  */
85 RCL_LIFECYCLE_PUBLIC
86 RCL_WARN_UNUSED
88 rcl_lifecycle_transition_map_fini(
89  rcl_lifecycle_transition_map_t * transition_map,
90  const rcl_allocator_t * allocator);
91 
93 /*
94  * This function registers a new state in the transition map.
95  *
96  * <hr>
97  * Attribute | Adherence
98  * ------------------ | -------------
99  * Allocates Memory | Yes
100  * Thread-Safe | No
101  * Uses Atomics | No
102  * Lock-Free | Yes
103  *
104  * \param[in] transition_map to be modified
105  * \param[in] state the state to register
106  * \param[in] allocator a valid allocator used to register the state machine
107  * \return `RCL_RET_OK` if the state was registered successfully, or
108  * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or
109  * \return `RCL_RET_LIFECYCLE_STATE_REGISTERED` if state is already registered.
110  */
111 RCL_LIFECYCLE_PUBLIC
112 RCL_WARN_UNUSED
113 rcl_ret_t
114 rcl_lifecycle_register_state(
115  rcl_lifecycle_transition_map_t * transition_map,
116  rcl_lifecycle_state_t state,
117  const rcl_allocator_t * allocator);
118 
120 /*
121  * This function registers a new transition in the transition map.
122  *
123  * <hr>
124  * Attribute | Adherence
125  * ------------------ | -------------
126  * Allocates Memory | Yes
127  * Thread-Safe | No
128  * Uses Atomics | No
129  * Lock-Free | Yes
130  *
131  * \param[in] transition_map to be modified
132  * \param[in] transition the transition to register
133  * \param[in] allocator a valid allocator used to register the state machine
134  * \return `RCL_RET_OK` if the state was deinitialized successfully, or
135  * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or
136  * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or
137  * \return `RCL_RET_LIFECYCLE_STATE_NOT_REGISTERED` if state is not registered, or
138  * \return `RCL_RET_ERROR` if an unspecified error occurs.
139  */
140 RCL_LIFECYCLE_PUBLIC
141 RCL_WARN_UNUSED
142 rcl_ret_t
143 rcl_lifecycle_register_transition(
144  rcl_lifecycle_transition_map_t * transition_map,
145  rcl_lifecycle_transition_t transition,
146  const rcl_allocator_t * allocator);
147 
149 /*
150  * A pointer to the internally lifecycle state struct is returned based on the `id`.
151  *
152  * <hr>
153  * Attribute | Adherence
154  * ------------------ | -------------
155  * Allocates Memory | No
156  * Thread-Safe | No
157  * Uses Atomics | No
158  * Lock-Free | Yes
159  *
160  * \param[in] transition_map
161  * \param[in] state_id
162  * \return pointer to a rcl_lifecycle_state_t or NULL if the state id doesn't exist
163  */
164 RCL_LIFECYCLE_PUBLIC
165 RCL_WARN_UNUSED
167 rcl_lifecycle_get_state(
168  rcl_lifecycle_transition_map_t * transition_map,
169  unsigned int state_id);
170 
172 /*
173  * A pointer to the internally lifecycle transition struct is returned based on the `label`.
174  *
175  * <hr>
176  * Attribute | Adherence
177  * ------------------ | -------------
178  * Allocates Memory | No
179  * Thread-Safe | No
180  * Uses Atomics | No
181  * Lock-Free | Yes
182  *
183  * \param[in] transition_map to be modified
184  * \param[in] state_id used to get the label to search
185  * \return pointer to a rcl_lifecycle_state_t or NULL if the state id doesn't exist
186  */
187 RCL_LIFECYCLE_PUBLIC
188 RCL_WARN_UNUSED
190 rcl_lifecycle_get_transitions(
191  rcl_lifecycle_transition_map_t * transition_map,
192  unsigned int transition_id);
193 
194 #ifdef __cplusplus
195 }
196 #endif
197 
198 #endif // RCL_LIFECYCLE__TRANSITION_MAP_H_
rcl_lifecycle_state_t
It contains the state of the lifecycle state machine.
Definition: data_types.h:30
rcl_ret_t
rmw_ret_t rcl_ret_t
rcl_lifecycle_transition_map_t
It contains the transition map states and transitions.
Definition: data_types.h:58
rcutils_allocator_t
rcl_lifecycle_transition_t
It contains the transitions of the lifecycle state machine.
Definition: data_types.h:44