rclcpp

The rclcpp_lifecycle package provides a prototype implementation for Lifecycle nodes in ROS 2. Lifecycle nodes allow for managed state transitions (e.g., Unconfigured, Inactive, Active), enabling more deterministic and controlled node behavior within a system.

For detailed architectural information on how Lifecycle works in ROS 2, refer to the official design document.

The rclcpp_components package provides tools for creating and managing dynamically loadable components in ROS 2. Instead of compiling every node into a single executable, you can develop components that can be loaded into a container at runtime, allowing for better resource management and modularity.

For a complete list of APIs, main components, and features, refer to the official rclcpp_components package info page.

The rclcpp_action package provides the C++ implementation of ROS 2 Action APIs. Actions are used for long-running tasks that require feedback and can be canceled. This package allows you to create both Action Servers and Action Clients in C++.

For a complete list of components, classes, and detailed API signatures, refer to the official rclcpp_action package info page.

Clock jump callbacks registered via Clock::create_jump_handler() are only invoked when using RCL_ROS_TIME (ROS time) and when simulation time is active.

Key behaviors:

• ROS Time: Jump handlers are triggered when simulation time starts, stops, or jumps.
• System/Steady Time: Jump handlers are not reliably triggered for system or steady time jumps, as these clock types do not provide the same jump detection mechanisms within the ROS middleware.
• Best Practice: Do not rely on jump handlers for RCL_SYSTEM_TIME or RCL_STEADY_TIME. Avoid actively adjusting system clocks while ROS nodes are running.

The rclcpp architecture manages the relationship between standard rclcpp::Node and rclcpp_lifecycle::LifecycleNode through various design patterns.

While LifecycleNode provides different semantics and interfaces, the project aims to keep these APIs in sync to reduce code duplication. The core functionality is often encapsulated in node_interface classes (e.g., rclcpp::node_interfaces::NodeTopics).

Users should be aware that while many methods are accessed via the Node object (e.g., node->create_publisher(...)), the underlying implementation relies on these specialized interface classes to maintain consistency across different node types.

The rclcpp_components package is classified as Quality Level 1. This implies the following stability guarantees:

• API Stability: The public API will not break within a released ROS distribution. No major releases are performed once a ROS distribution is released.
• ABI Stability: As a C++ package, it maintains ABI stability within a released ROS distribution.
• Versioning: It uses semver (semantic versioning) and is currently at a stable version (>= 1.0.0).

To avoid the side effects and potential state corruption caused by using validation callbacks (like add_on_set_parameters_callback) for logic, use the proposed add_post_set_parameters_callback.

This callback is triggered only after parameters have been successfully validated and set. It is the appropriate place to update internal class attributes or trigger logic that depends on the new parameter values. This is more efficient and reliable than subscribing to the /parameter_events topic, as it avoids the latency of waiting for an executor to process external messages.

In rclcpp, many entities like Publisher and Subscription are scoped. This means:

1. Automatic Registration: When created, they are automatically added to the ROS graph.
2. Automatic Removal: When the object is destroyed (e.g., goes out of scope), it is removed from the ROS graph.
3. Shared Ownership: These entities use std::shared_ptr and std::weak_ptr to manage shared state between the user and the system (e.g., an Executor).

Important Lifecycle Note

Because of shared ownership, letting a Subscription go out of scope does not guarantee immediate destruction or removal from the graph. The entity will only be destroyed and removed once both the user and the system (like an Executor) have released their references.

If you need to ensure an entity is destroyed, you must ensure all shared references held by the system are also released.