Added documentation to rcl_lifecycle (#622)
* Added documentation to rcl_lifecycle Signed-off-by: ahcorde <ahcorde@gmail.com> * Adding more documentation to rcl_lifecycle Signed-off-by: ahcorde <ahcorde@gmail.com> * Update rcl_lifecycle/include/rcl_lifecycle/default_state_machine.h Co-Authored-By: Jorge Perez <jjperez@ekumenlabs.com> Update rcl_lifecycle/include/rcl_lifecycle/default_state_machine.h Co-Authored-By: Jorge Perez <jjperez@ekumenlabs.com> Update rcl_lifecycle/include/rcl_lifecycle/transition_map.h Co-Authored-By: Jorge Perez <jjperez@ekumenlabs.com> Update rcl_lifecycle/include/rcl_lifecycle/rcl_lifecycle.h Co-Authored-By: Jorge Perez <jjperez@ekumenlabs.com> Update rcl_lifecycle/include/rcl_lifecycle/transition_map.h Co-Authored-By: Jorge Perez <jjperez@ekumenlabs.com> Signed-off-by: ahcorde <ahcorde@gmail.com> * Added feedback Signed-off-by: ahcorde <ahcorde@gmail.com> * Added more feedback Signed-off-by: ahcorde <ahcorde@gmail.com> * Fixed uncrustify Signed-off-by: ahcorde <ahcorde@gmail.com> Co-authored-by: Jorge Perez <jjperez@ekumenlabs.com>
This commit is contained in:
Alejandro Hernández Cordero
GitHub
parent
65feb5c725
commit
e00b4b8d2a
3 changed files with 444 additions and 1 deletions
|
|
@ -36,6 +36,54 @@ RCL_LIFECYCLE_PUBLIC extern const char * rcl_lifecycle_transition_success_label;
|
|||
RCL_LIFECYCLE_PUBLIC extern const char * rcl_lifecycle_transition_failure_label;
|
||||
RCL_LIFECYCLE_PUBLIC extern const char * rcl_lifecycle_transition_error_label;
|
||||
|
||||
/// Initialize a default state machine
|
||||
/*
|
||||
* This function initializes a default state machine. It registers all: primary states,
|
||||
* transition states, transitions and the initial state. The primary state is unconfigured.
|
||||
*
|
||||
* States: unknown, unconfigured, inactive, active and finalized.
|
||||
* Transition states: configuring, cleaningup, activating, deactivating, errorprocessing
|
||||
* and shuttingdown.
|
||||
* Transitions:
|
||||
* - unconfigured to configuring
|
||||
* - unconfigured to shuttingdown
|
||||
* - configuring to inactive
|
||||
* - configuring to unconfigured
|
||||
* - configuring to errorprocessing
|
||||
* - inactive to activating
|
||||
* - inactive to cleaningup
|
||||
* - inactive to shuttingdown
|
||||
* - cleaningup to unconfigured
|
||||
* - cleaningup to inactive
|
||||
* - cleaniningup to errorprocessing
|
||||
* - activating to active
|
||||
* - activating to inactive
|
||||
* - activating to errorprocessing
|
||||
* - active to deactivating
|
||||
* - active to shuttingdown
|
||||
* - deactivating to inactive
|
||||
* - deactivating to active
|
||||
* - deactivating to errorprocessing
|
||||
* - shutting down to finalized
|
||||
* - shutting down to finalized
|
||||
* - shutting down to errorprocessing
|
||||
* - errorprocessing to uncofigured
|
||||
* - errorprocessing to finalized
|
||||
* - errorprocessing to finalized
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | Yes
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[inout] state_machine struct to be initialized
|
||||
* \param[in] allocator a valid allocator used to initialized the state machine
|
||||
* \return `RCL_RET_OK` if the state machine was initialized successfully, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
|
|||
|
|
@ -12,6 +12,24 @@
|
|||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
/** \mainpage rcl: Common functionality ROS lifecycle
|
||||
*
|
||||
* `rcl_lifecycle` provides a pure C implementation of the ROS concept of lifecycle.
|
||||
* It builds on top of the implementation of topics and services in `rcl`.
|
||||
*
|
||||
* `rcl_lifecycle` consists of functions and structs for the following ROS lifecycle entities:
|
||||
*
|
||||
* - Lifecycle states
|
||||
* - Lifecycle transitions
|
||||
* - Lifecycle state machine
|
||||
* - Lifecycle triggers
|
||||
*
|
||||
* Some useful abstractions:
|
||||
*
|
||||
* - Return codes and other types
|
||||
* - rcl_lifecycle/data_types.h
|
||||
*/
|
||||
|
||||
#ifndef RCL_LIFECYCLE__RCL_LIFECYCLE_H_
|
||||
#define RCL_LIFECYCLE__RCL_LIFECYCLE_H_
|
||||
|
||||
|
|
@ -26,10 +44,41 @@ extern "C"
|
|||
#include "rcl_lifecycle/default_state_machine.h"
|
||||
#include "rcl_lifecycle/visibility_control.h"
|
||||
|
||||
/// Return a rcl_lifecycle_state_t struct with members set to `NULL` or 0.
|
||||
/**
|
||||
* Should be called to get a null rcl_lifecycle_state_t before passing to
|
||||
* rcl_lifecycle_state_init().
|
||||
*
|
||||
* \return rcl_lifecycle_state_t a initilized struct
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
rcl_lifecycle_state_t
|
||||
rcl_lifecycle_get_zero_initialized_state();
|
||||
|
||||
/// Initialize a rcl_lifecycle_state_init.
|
||||
/**
|
||||
* This function initializes a state based on an `id` and a `label`.
|
||||
*
|
||||
* The given `rcl_lifecycle_state_t` must be zero initialized with the function
|
||||
* `rcl_lifecycle_get_zero_initialized_state()` and must not be already initialized
|
||||
* by this function.
|
||||
* The allocator will be used to allocate the label string.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | Yes
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[inout] state pointer to the state struct to be initialized
|
||||
* \param[in] id identifier of the state
|
||||
* \param[in] label label of the state
|
||||
* \param[in] allocator a valid allocator used to initialized the lifecycle state
|
||||
* \return `RCL_RET_OK` if state was initialized successfully, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
@ -39,6 +88,26 @@ rcl_lifecycle_state_init(
|
|||
const char * label,
|
||||
const rcl_allocator_t * allocator);
|
||||
|
||||
/// Finalize a rcl_lifecycle_state_t.
|
||||
/**
|
||||
*
|
||||
* Calling this will set the rcl_lifecycle_state_t struct into the an unitialized state that is
|
||||
* functionally the same as before rcl_lifecycle_state_init was called. This function make the
|
||||
* rcl_lifecycle_state_t invalid.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | Yes
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[inout] state struct to be finalized
|
||||
* \param[in] allocator a valid allocator used to finalize the lifecycle state
|
||||
* \return `RCL_RET_OK` if the state was finalized successfully, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
@ -46,16 +115,44 @@ rcl_lifecycle_state_fini(
|
|||
rcl_lifecycle_state_t * state,
|
||||
const rcl_allocator_t * allocator);
|
||||
|
||||
/// Return a rcl_lifecycle_transition_t struct with members set to `NULL` or 0.
|
||||
/**
|
||||
* Should be called to get a null rcl_lifecycle_transition_t before passing to
|
||||
* rcl_lifecycle_transition_init().
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
rcl_lifecycle_transition_t
|
||||
rcl_lifecycle_get_zero_initialized_transition();
|
||||
|
||||
/// Initialize transition with existing states
|
||||
/// Initialize a transition from a start state to the goal state.
|
||||
/**
|
||||
* The given `rcl_lifecycle_transition_t` must be zero initialized with the function
|
||||
* `rcl_lifecycle_get_zero_initialized_transition()` and must not be already initialized
|
||||
* by this function.
|
||||
* The allocator will be used to allocate the label string and the rcl_lifecycle_state_t structs.
|
||||
*
|
||||
* Note: the transition pointer will take ownership
|
||||
* of the start and goal state. When calling
|
||||
* rcl_lifecycle_transition_fini(), the two states
|
||||
* will be freed.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | Yes
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] transition to a preallocated, zero-initialized transition structure
|
||||
* to be initialized.
|
||||
* \param[in] id identifier of the transition
|
||||
* \param[in] label label of the transition
|
||||
* \param[in] start the value where the transition is initialized
|
||||
* \param[in] goal the objetive of the transition
|
||||
* \param[in] allocator a valid allocator used to finalize the lifecycle state
|
||||
* \return `RCL_RET_OK` if the transition is initialized successfully, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
|
|
@ -68,6 +165,25 @@ rcl_lifecycle_transition_init(
|
|||
rcl_lifecycle_state_t * goal,
|
||||
const rcl_allocator_t * allocator);
|
||||
|
||||
/// Finalize a rcl_lifecycle_transition_t.
|
||||
/**
|
||||
* Calling this will set the rcl_lifecycle_transition_t struct into the an unitialized state that is
|
||||
* functionally the same as before rcl_lifecycle_transition_init was called. This function make the
|
||||
* rcl_lifecycle_transition_t invalid.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | Yes
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[inout] transition struct to be finalized
|
||||
* \param[in] allocator a valid allocator used to finalize the transition
|
||||
* \return `RCL_RET_OK` if the state was finalized successfully, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
@ -75,10 +191,46 @@ rcl_lifecycle_transition_fini(
|
|||
rcl_lifecycle_transition_t * transition,
|
||||
const rcl_allocator_t * allocator);
|
||||
|
||||
/// Return a rcl_lifecycle_state_machine_t struct with members set to `NULL` or 0.
|
||||
/**
|
||||
* Should be called to get a null rcl_lifecycle_state_machine_t before passing to
|
||||
* rcl_lifecycle_state_machine_init().
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
rcl_lifecycle_state_machine_t
|
||||
rcl_lifecycle_get_zero_initialized_state_machine();
|
||||
|
||||
/// Initialize state machine
|
||||
/**
|
||||
* This function initialize the state machine: one publisher to publish transitions messages
|
||||
* and a set of services to get information about states and transitions.
|
||||
* If `default_state` is `true` then a new default state machine is initialized.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | Yes
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[inout] state_machine struct to be initialized
|
||||
* \param[in] node_handle a valid (not finalized) handle to the node used to create the publisher
|
||||
* and the services
|
||||
* \param[in] ts_pub_notify pointer to transition publisher, it used to publish the transitions
|
||||
* \param[in] ts_srv_change_state pointer to the service that allows to trigger changes on the state
|
||||
* \param[in] ts_srv_get_state pointer to the service that allows to get the current state
|
||||
* \param[in] ts_srv_get_available_states pointer to the service that allows to get the available states
|
||||
* \param[in] ts_srv_get_available_transitions pointer to the service that allows to get the
|
||||
* available transitions
|
||||
* \param[in] ts_srv_get_transition_graph pointer to the service that allows to get transitions from
|
||||
* the graph
|
||||
* \param[in] default_states if `true` a new default state machine is initialized, otherwise
|
||||
* the state_machine pointer is only used to initialize the interfaces
|
||||
* \param[in] allocator a valid allocator used to initialized the state machine
|
||||
* \return `RCL_RET_OK` if the state machine was initialized successfully, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
@ -94,6 +246,26 @@ rcl_lifecycle_state_machine_init(
|
|||
bool default_states,
|
||||
const rcl_allocator_t * allocator);
|
||||
|
||||
/// Finalize a rcl_lifecycle_state_machine_t.
|
||||
/**
|
||||
* Calling this will set the rcl_lifecycle_state_machine_t struct into the an unitialized state that is
|
||||
* functionally the same as before rcl_lifecycle_state_machine_init was called. This function make the
|
||||
* rcl_lifecycle_state_machine_t invalid.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | Yes
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[inout] state_machine struct to be finalized
|
||||
* \param[in] node_handle valid (not finalized) handle to the node
|
||||
* \param[in] allocator a valid allocator used to finalize the state machine
|
||||
* \return `RCL_RET_OK` if the state was finalized successfully, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
@ -102,12 +274,47 @@ rcl_lifecycle_state_machine_fini(
|
|||
rcl_node_t * node_handle,
|
||||
const rcl_allocator_t * allocator);
|
||||
|
||||
/// Check if a state machine is active.
|
||||
/**
|
||||
* If the state is initialized then returns `RCL_RET_OK`, otherwise returns `RCL_RET_ERROR`
|
||||
* In the case where `RCL_RET_ERROR` is to be returned, an error message is set.
|
||||
* This function cannot fail.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | No
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] state_machine pointer to the state machine struct
|
||||
* \return `RCL_RET_OK` if the state is initialized, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
rcl_lifecycle_state_machine_is_initialized(
|
||||
const rcl_lifecycle_state_machine_t * state_machine);
|
||||
|
||||
/// Get a state by id.
|
||||
/**
|
||||
* A pointer to the internally transition struct is returned
|
||||
* based on the `id`. If the `id` is not set in the state then returns NULL.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | No
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] state pointer to the state struct
|
||||
* \param[in] id identifier to be find in the valid transitions
|
||||
* \return a pointer to the lifecycle transition if the `id` exists or otherwise it return NULL
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
const rcl_lifecycle_transition_t *
|
||||
|
|
@ -115,6 +322,23 @@ rcl_lifecycle_get_transition_by_id(
|
|||
const rcl_lifecycle_state_t * state,
|
||||
uint8_t id);
|
||||
|
||||
/// Get a state by id.
|
||||
/**
|
||||
* A pointer to the internally transition struct is returned
|
||||
* based on the `label`. If the `label` is not set in the state then returns NULL.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | No
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] state pointer to the state struct
|
||||
* \param[in] label label to be find in the valid transitions
|
||||
* \return a pointer to the lifecycle transition if the label exists or otherwise it return NULL
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
const rcl_lifecycle_transition_t *
|
||||
|
|
@ -122,6 +346,27 @@ rcl_lifecycle_get_transition_by_label(
|
|||
const rcl_lifecycle_state_t * state,
|
||||
const char * label);
|
||||
|
||||
/// Trigger a state by id.
|
||||
/**
|
||||
* This function will trigger a transition based on the `id`. If the argument
|
||||
* `publish_notification` is `true` then a message will be published in the
|
||||
* ROS 2 network notifying the transition, if `false` no message will be published.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | No
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] state_machine pointer to the state machine struct
|
||||
* \param[in] id identifier of the transition to be triggered
|
||||
* \param[in] publish_notification if the value is `true` a message will be published
|
||||
* notifying the transition, otherwise no message will be published
|
||||
* \return `RCL_RET_OK` if the transition was triggered successfully, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
@ -130,6 +375,27 @@ rcl_lifecycle_trigger_transition_by_id(
|
|||
uint8_t id,
|
||||
bool publish_notification);
|
||||
|
||||
/// Trigger a state by label.
|
||||
/**
|
||||
* This function will trigger a transition base on the `label`. If the argument
|
||||
* `publish_notification` is `true` then a message will be published in the
|
||||
* ROS 2 network notifying the transition, if `false` no message will be published.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | No
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] state_machine pointer to the state machine struct
|
||||
* \param[in] label of the transition to be triggered
|
||||
* \param[in] publish_notification if the value is `true` a message will be published
|
||||
* notifying the transition, otherwise no message will be published
|
||||
* \return `RCL_RET_OK` if the transition was triggered successfully, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
@ -138,6 +404,21 @@ rcl_lifecycle_trigger_transition_by_label(
|
|||
const char * label,
|
||||
bool publish_notification);
|
||||
|
||||
/// Print the state machine data
|
||||
/**
|
||||
* This function will print in the standard output the data in the
|
||||
* rcl_lifecycle_state_machine_t struct.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | No
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] state_machine pointer to the state machine struct to print
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
void
|
||||
rcl_print_state_machine(const rcl_lifecycle_state_machine_t * state_machine);
|
||||
|
|
|
|||
|
|
@ -25,17 +25,61 @@ extern "C"
|
|||
{
|
||||
#endif
|
||||
|
||||
/// Initialize a rcl_lifecycle_state_init.
|
||||
/*
|
||||
* Should be called to get a null rcl_lifecycle_transition_map_t before passing to
|
||||
* rcl_lifecycle_register_state() or rcl_lifecycle_register_transition().
|
||||
*
|
||||
* \return rcl_lifecycle_transition_map_t a initilized struct
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_lifecycle_transition_map_t
|
||||
rcl_lifecycle_get_zero_initialized_transition_map();
|
||||
|
||||
/// Check if a transition map is active using a rcl_lifecycle_state_machine_t.
|
||||
/*
|
||||
* The function checks if the transition map is initialized. It returns `RCL_RET_OK`
|
||||
* if the transition map is initialized successfully or `RCL_RET_ERROR` if the transition
|
||||
* map is not initialized.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | No
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] transition_map pointer to the transition map struct to check
|
||||
* \return `RCL_RET_OK` if the transition map is initialized successfully, or
|
||||
* \return `RCL_RET_ERROR` if the transition map is not initialized.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
rcl_lifecycle_transition_map_is_initialized(
|
||||
const rcl_lifecycle_transition_map_t * transition_map);
|
||||
|
||||
/// Finalize a rcl_lifecycle_transition_map_t.
|
||||
/*
|
||||
* Calling this will set the rcl_lifecycle_transition_map_t struct into the an unitialized state that is
|
||||
* functionally the same as before rcl_lifecycle_register_state or
|
||||
* rcl_lifecycle_register_transition was called. This function make the rcl_lifecycle_transition_map_t invalid.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | Yes
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[inout] transition_map struct to be deinitialized
|
||||
* \param[in] allocator a valid allocator used to deinitialized the state machine
|
||||
* \return `RCL_RET_OK` if the state was deinitialized successfully, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
@ -43,6 +87,25 @@ rcl_lifecycle_transition_map_fini(
|
|||
rcl_lifecycle_transition_map_t * transition_map,
|
||||
const rcl_allocator_t * allocator);
|
||||
|
||||
/// Register a state
|
||||
/*
|
||||
* This function registers a new state in the transition map.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | Yes
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] map to be modified
|
||||
* \param[in] state the state to register
|
||||
* \param[in] allocator a valid allocator used to register the state machine
|
||||
* \return `RCL_RET_OK` if the state was registered successfully, or
|
||||
* \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
@ -51,6 +114,25 @@ rcl_lifecycle_register_state(
|
|||
rcl_lifecycle_state_t state,
|
||||
const rcl_allocator_t * allocator);
|
||||
|
||||
/// Register a transition
|
||||
/*
|
||||
* This function registers a new transition in the transition map.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | Yes
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] transition_map to be modified
|
||||
* \param[in] transition the transition to register
|
||||
* \param[in] allocator a valid allocator used to register the state machine
|
||||
* \return `RCL_RET_OK` if the state was deinitialized successfully, or
|
||||
* \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or
|
||||
* \return `RCL_RET_ERROR` if an unspecified error occurs.
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_ret_t
|
||||
|
|
@ -59,6 +141,22 @@ rcl_lifecycle_register_transition(
|
|||
rcl_lifecycle_transition_t transition,
|
||||
const rcl_allocator_t * allocator);
|
||||
|
||||
/// Get the state from a transition map based on the state id
|
||||
/*
|
||||
* A pointer to the internally lifecycle state struct is returned based on the `id`.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | No
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] transition_map
|
||||
* \param[in] state_id
|
||||
* \return pointer to a rcl_lifecycle_state_t or NULL if the state id doesn't exist
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_lifecycle_state_t *
|
||||
|
|
@ -66,6 +164,22 @@ rcl_lifecycle_get_state(
|
|||
rcl_lifecycle_transition_map_t * transition_map,
|
||||
unsigned int state_id);
|
||||
|
||||
/// Get the state from a transition map based on the state id
|
||||
/*
|
||||
* A pointer to the internally lifecycle transition struct is returned based on the `label`.
|
||||
*
|
||||
* <hr>
|
||||
* Attribute | Adherence
|
||||
* ------------------ | -------------
|
||||
* Allocates Memory | No
|
||||
* Thread-Safe | No
|
||||
* Uses Atomics | No
|
||||
* Lock-Free | Yes
|
||||
*
|
||||
* \param[in] transition_map to be modified
|
||||
* \param[in] state_id used to get the label to search
|
||||
* \return pointer to a rcl_lifecycle_state_t or NULL if the state id doesn't exist
|
||||
*/
|
||||
RCL_LIFECYCLE_PUBLIC
|
||||
RCL_WARN_UNUSED
|
||||
rcl_lifecycle_transition_t *
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue