Improved documentation of rcl_XYZ_set_on_new_XYZ_callback

rcl/CHANGELOG.rst

@@ -2,6 +2,9 @@
 Changelog for package rcl
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
+10.3.1 (2026-02-09)
+-------------------
+
 10.3.0 (2026-01-29)
 -------------------
 * rcl_logging_implementation package support. (`#1276 <https://github.com/ros2/rcl/issues/1276>`_)

rcl/include/rcl/client.h

@@ -475,6 +475,14 @@ rcl_client_response_subscription_get_actual_qos(const rcl_client_t * client);
  *
  * \sa rmw_client_set_on_new_response_callback for details about this function.
  *
+ * Since this callback is called from the middleware, you should
+ * aim to make it fast and not blocking. This callback is intended to implement an event driven executor and
+ * not process data directly.  
+ * 
+ * Blocking or performing synchronous work here may cause subsequent callbacks
+ * or responses to execute in executor threads different than the current 
+ * middleware thread.
+ * 
  * <hr>
  * Attribute          | Adherence
  * ------------------ | -------------

rcl/include/rcl/service.h

@@ -507,6 +507,14 @@ rcl_service_response_publisher_get_actual_qos(const rcl_service_t * service);
  *
  * \sa rmw_service_set_on_new_request_callback for details about this function.
  *
+ * Since this callback is called from the middleware, you should
+ * aim to make it fast and not blocking. This callback is intended to implement an event driven executor and
+ * not process data directly.  
+ * 
+ * Blocking or performing synchronous work here may cause subsequent callbacks
+ * or responses to execute in executor threads different than the current 
+ * middleware thread.
+ * 
  * <hr>
  * Attribute          | Adherence
  * ------------------ | -------------

rcl/include/rcl/subscription.h

@@ -886,6 +886,14 @@ rcl_subscription_can_loan_messages(const rcl_subscription_t * subscription);
  * \sa rmw_subscription_set_on_new_message_callback for details about this
  * function.
  *
+ * Since this callback is called from the middleware, you should
+ * aim to make it fast and not blocking. This callback is intended to implement an event driven executor and
+ * not process data directly.  
+ * 
+ * Blocking or performing synchronous work here may cause subsequent callbacks
+ * or responses to execute in executor threads different than the current 
+ * middleware thread.
+ * 
  * <hr>
  * Attribute          | Adherence
  * ------------------ | -------------

rcl/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>rcl</name>
-  <version>10.3.0</version>
+  <version>10.3.1</version>
   <description>The ROS client library common implementation.
     This package contains an API which builds on the ROS middleware API and is optionally built upon by the other ROS client libraries.
   </description>

rcl_action/CHANGELOG.rst

@@ -2,6 +2,9 @@
 Changelog for package rcl_action
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+10.3.1 (2026-02-09)
+-------------------
+
 10.3.0 (2026-01-29)
 -------------------
 

rcl_action/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format2.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="2">
   <name>rcl_action</name>
-  <version>10.3.0</version>
+  <version>10.3.1</version>
   <description>Package containing a C-based ROS action implementation</description>
 
   <maintainer email="audrow@openrobotics.org">Audrow Nash</maintainer>

rcl_lifecycle/CHANGELOG.rst

@@ -2,6 +2,11 @@
 Changelog for package rcl_lifecycle
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+10.3.1 (2026-02-09)
+-------------------
+* Populate Transitions in Transition Events (continuation) (`#1269 <https://github.com/ros2/rcl/issues/1269>`_)
+* Contributors: Jasper van Brakel
+
 10.3.0 (2026-01-29)
 -------------------
 

rcl_lifecycle/include/rcl_lifecycle/data_types.h

@@ -74,6 +74,8 @@ typedef struct rcl_lifecycle_com_interface_s
 {
   /// Handle to the node used to create the publisher and the services
   rcl_node_t * node_handle;
+  /// Node clock for timestamping transition event messages
+  rcl_clock_t * clock;
   /// Event used to publish the transitions
   rcl_publisher_t pub_transition_event;
   /// Service that allows to trigger changes on the state

rcl_lifecycle/include/rcl_lifecycle/rcl_lifecycle.h

@@ -225,6 +225,7 @@ rcl_lifecycle_get_zero_initialized_state_machine(void);
  * \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] clock the clock associated with the node used for time stamping transition events
  * \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
@@ -244,6 +245,7 @@ rcl_ret_t
 rcl_lifecycle_state_machine_init(
   rcl_lifecycle_state_machine_t * state_machine,
   rcl_node_t * node_handle,
+  rcl_clock_t * clock,
   const rosidl_message_type_support_t * ts_pub_notify,
   const rosidl_service_type_support_t * ts_srv_change_state,
   const rosidl_service_type_support_t * ts_srv_get_state,

rcl_lifecycle/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format2.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="2">
   <name>rcl_lifecycle</name>
-  <version>10.3.0</version>
+  <version>10.3.1</version>
   <description>Package containing a C-based lifecycle implementation</description>
 
   <maintainer email="audrow@openrobotics.org">Audrow Nash</maintainer>

rcl_lifecycle/src/com_interface.c

@@ -49,6 +49,7 @@ rcl_lifecycle_get_zero_initialized_com_interface(void)
 {
   rcl_lifecycle_com_interface_t com_interface;
   com_interface.node_handle = NULL;
+  com_interface.clock = NULL;
   com_interface.pub_transition_event = rcl_get_zero_initialized_publisher();
   com_interface.srv_change_state = rcl_get_zero_initialized_service();
   com_interface.srv_get_state = rcl_get_zero_initialized_service();
@@ -64,6 +65,7 @@ rcl_ret_t
 rcl_lifecycle_com_interface_init(
   rcl_lifecycle_com_interface_t * com_interface,
   rcl_node_t * node_handle,
+  rcl_clock_t * clock,
   const rosidl_message_type_support_t * ts_pub_notify,
   const rosidl_service_type_support_t * ts_srv_change_state,
   const rosidl_service_type_support_t * ts_srv_get_state,
@@ -72,7 +74,7 @@ rcl_lifecycle_com_interface_init(
   const rosidl_service_type_support_t * ts_srv_get_transition_graph)
 {
   rcl_ret_t ret = rcl_lifecycle_com_interface_publisher_init(
-    com_interface, node_handle, ts_pub_notify);
+    com_interface, node_handle, clock, ts_pub_notify);
   if (ret != RCL_RET_OK) {
     return ret;
   }
@@ -100,12 +102,18 @@ rcl_ret_t
 rcl_lifecycle_com_interface_publisher_init(
   rcl_lifecycle_com_interface_t * com_interface,
   rcl_node_t * node_handle,
+  rcl_clock_t * clock,
   const rosidl_message_type_support_t * ts_pub_notify)
 {
   RCL_CHECK_ARGUMENT_FOR_NULL(com_interface, RCL_RET_INVALID_ARGUMENT);
   RCL_CHECK_ARGUMENT_FOR_NULL(node_handle, RCL_RET_INVALID_ARGUMENT);
   RCL_CHECK_ARGUMENT_FOR_NULL(ts_pub_notify, RCL_RET_INVALID_ARGUMENT);
 
+  if (!rcl_clock_valid(clock)) {
+    RCL_SET_ERROR_MSG("invalid clock");
+    return RCL_RET_INVALID_ARGUMENT;
+  }
+
   // initialize publisher
   rcl_publisher_options_t publisher_options = rcl_publisher_get_default_options();
   rcl_ret_t ret = rcl_publisher_init(
@@ -118,6 +126,7 @@ rcl_lifecycle_com_interface_publisher_init(
 
   // initialize static message for notification
   lifecycle_msgs__msg__TransitionEvent__init(&com_interface->msg);
+  com_interface->clock = clock;
 
   return RCL_RET_OK;
 
@@ -325,12 +334,23 @@ rcl_lifecycle_com_interface_fini(
 rcl_ret_t
 rcl_lifecycle_com_interface_publish_notification(
   rcl_lifecycle_com_interface_t * com_interface,
-  const rcl_lifecycle_state_t * start, const rcl_lifecycle_state_t * goal)
+  const rcl_lifecycle_transition_t * transition)
 {
-  com_interface->msg.start_state.id = start->id;
-  rosidl_runtime_c__String__assign(&com_interface->msg.start_state.label, start->label);
-  com_interface->msg.goal_state.id = goal->id;
-  rosidl_runtime_c__String__assign(&com_interface->msg.goal_state.label, goal->label);
+  // Get the current time based on the rcl_clock
+  rcl_time_point_value_t timestamp;
+  rcl_ret_t time_ret = rcl_clock_get_now(com_interface->clock, &timestamp);
+  if (time_ret != RCL_RET_OK) {
+    return time_ret;  // rcl error state should already be set.
+  }
+
+  com_interface->msg.stamp.sec = (int32_t) RCL_NS_TO_S(timestamp);
+  com_interface->msg.stamp.nanosec = (uint32_t) (timestamp % RCL_S_TO_NS(1));
+  com_interface->msg.transition.id = (uint8_t) transition->id;
+  rosidl_runtime_c__String__assign(&com_interface->msg.transition.label, transition->label);
+  com_interface->msg.start_state.id = transition->start->id;
+  rosidl_runtime_c__String__assign(&com_interface->msg.start_state.label, transition->start->label);
+  com_interface->msg.goal_state.id = transition->goal->id;
+  rosidl_runtime_c__String__assign(&com_interface->msg.goal_state.label, transition->goal->label);
 
   return rcl_publish(&com_interface->pub_transition_event, &com_interface->msg, NULL);
 }

rcl_lifecycle/src/com_interface.h

@@ -32,6 +32,7 @@ RCL_WARN_UNUSED
 rcl_lifecycle_com_interface_init(
   rcl_lifecycle_com_interface_t * com_interface,
   rcl_node_t * node_handle,
+  rcl_clock_t * clock,
   const rosidl_message_type_support_t * ts_pub_notify,
   const rosidl_service_type_support_t * ts_srv_change_state,
   const rosidl_service_type_support_t * ts_srv_get_state,
@@ -44,6 +45,7 @@ RCL_WARN_UNUSED
 rcl_lifecycle_com_interface_publisher_init(
   rcl_lifecycle_com_interface_t * com_interface,
   rcl_node_t * node_handle,
+  rcl_clock_t * clock,
   const rosidl_message_type_support_t * ts_pub_notify);
 
 rcl_ret_t
@@ -79,7 +81,7 @@ rcl_ret_t
 RCL_WARN_UNUSED
 rcl_lifecycle_com_interface_publish_notification(
   rcl_lifecycle_com_interface_t * com_interface,
-  const rcl_lifecycle_state_t * start, const rcl_lifecycle_state_t * goal);
+  const rcl_lifecycle_transition_t * transition);
 
 #ifdef __cplusplus
 }

rcl_lifecycle/src/rcl_lifecycle.c

@@ -194,6 +194,7 @@ rcl_ret_t
 rcl_lifecycle_state_machine_init(
   rcl_lifecycle_state_machine_t * state_machine,
   rcl_node_t * node_handle,
+  rcl_clock_t * clock,
   const rosidl_message_type_support_t * ts_pub_notify,
   const rosidl_service_type_support_t * ts_srv_change_state,
   const rosidl_service_type_support_t * ts_srv_get_state,
@@ -208,6 +209,9 @@ rcl_lifecycle_state_machine_init(
   RCL_CHECK_FOR_NULL_WITH_MSG(
     node_handle, "Node handle is null\n", return RCL_RET_INVALID_ARGUMENT);
 
+  RCL_CHECK_FOR_NULL_WITH_MSG(
+    clock, "Clock is null\n", return RCL_RET_INVALID_ARGUMENT);
+
   RCL_CHECK_ALLOCATOR_WITH_MSG(
     &state_machine_options->allocator, "can't initialize state machine, no allocator given\n",
     return RCL_RET_INVALID_ARGUMENT);
@@ -218,15 +222,15 @@ rcl_lifecycle_state_machine_init(
   if (state_machine->options.enable_com_interface) {
     rcl_ret_t ret = rcl_lifecycle_com_interface_init(
       &state_machine->com_interface, node_handle,
-      ts_pub_notify,
+      clock, ts_pub_notify,
       ts_srv_change_state, ts_srv_get_state,
       ts_srv_get_available_states, ts_srv_get_available_transitions, ts_srv_get_transition_graph);
     if (ret != RCL_RET_OK) {
       return RCL_RET_ERROR;
     }
   } else {
     rcl_ret_t ret = rcl_lifecycle_com_interface_publisher_init(
-      &state_machine->com_interface, node_handle, ts_pub_notify);
+      &state_machine->com_interface, node_handle, clock, ts_pub_notify);
     if (ret != RCL_RET_OK) {
       return RCL_RET_ERROR;
     }
@@ -379,7 +383,7 @@ _trigger_transition(
 
   if (publish_notification) {
     rcl_ret_t fcn_ret = rcl_lifecycle_com_interface_publish_notification(
-      &state_machine->com_interface, transition->start, state_machine->current_state);
+      &state_machine->com_interface, transition);
     if (fcn_ret != RCL_RET_OK) {
       rcl_error_string_t error_string = rcl_get_error_string();
       rcutils_reset_error();