From 992eab1434998346c551c6ddfd21853d65b2f91e Mon Sep 17 00:00:00 2001 From: Jason Beach Date: Sat, 20 Aug 2022 00:08:19 -0400 Subject: [PATCH] force compiler warning if callback handles not captured clarify documentation to show that not capturing returned handles will result in callbacks immediately being unregistered Signed-off-by: Jason Beach --- .../rclcpp/parameter_event_handler.hpp | 23 +++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/rclcpp/include/rclcpp/parameter_event_handler.hpp b/rclcpp/include/rclcpp/parameter_event_handler.hpp index 52a0233966..d55140e00f 100644 --- a/rclcpp/include/rclcpp/parameter_event_handler.hpp +++ b/rclcpp/include/rclcpp/parameter_event_handler.hpp @@ -86,6 +86,9 @@ struct ParameterEventCallbackHandle * the ROS node supplied in the ParameterEventHandler constructor. * The callback, a lambda function in this case, simply prints out the value of the parameter. * + * Note: the object returned from add_parameter_callback must be captured or the callback will + * be immediately unregistered. + * * You may also monitor for changes to parameters in other nodes by supplying the node * name to add_parameter_callback: * @@ -103,8 +106,8 @@ struct ParameterEventCallbackHandle * In this case, the callback will be invoked whenever "some_remote_param_name" changes * on remote node "some_remote_node_name". * - * To remove a parameter callback, call remove_parameter_callback, passing the handle returned - * from add_parameter_callback: + * To remove a parameter callback, reset the callback handle smart pointer or call + * remove_parameter_callback, passing the handle returned from add_parameter_callback: * * param_handler->remove_parameter_callback(handle2); * @@ -152,9 +155,12 @@ struct ParameterEventCallbackHandle * For both parameter callbacks and parameter event callbacks, when multiple callbacks are added, * the callbacks are invoked last-in, first-called order (LIFO). * - * To remove a parameter event callback, use: + * Note: the callback handle returned from add_parameter_event_callback must be captured or + * the callback will immediately be unregistered. + * + * To remove a parameter event callback, reset the callback smart pointer or use: * - * param_handler->remove_event_parameter_callback(handle); + * param_handler->remove_event_parameter_callback(handle3); */ class ParameterEventHandler { @@ -189,10 +195,14 @@ class ParameterEventHandler /** * This function may be called multiple times to set multiple parameter event callbacks. * + * Note: if the returned callback handle smart pointer is not captured, the callback is + * immediatedly unregistered. A compiler warning should be generated to warn of this. + * * \param[in] callback Function callback to be invoked on parameter updates. * \returns A handle used to refer to the callback. */ RCLCPP_PUBLIC + RCUTILS_WARN_UNUSED ParameterEventCallbackHandle::SharedPtr add_parameter_event_callback( ParameterEventCallbackType callback); @@ -212,12 +222,17 @@ class ParameterEventHandler /** * If a node_name is not provided, defaults to the current node. * + * Note: if the returned callback handle smart pointer is not captured, the callback + * is immediately unregistered. A compiler warning should be generated to warn + * of this. + * * \param[in] parameter_name Name of parameter to monitor. * \param[in] callback Function callback to be invoked upon parameter update. * \param[in] node_name Name of node which hosts the parameter. * \returns A handle used to refer to the callback. */ RCLCPP_PUBLIC + RCUTILS_WARN_UNUSED ParameterCallbackHandle::SharedPtr add_parameter_callback( const std::string & parameter_name,