A class used to "handle" (monitor and respond to) changes to parameters. More...

#include <rclcpp/parameter_event_handler.hpp>

Collaboration diagram for rclcpp::ParameterEventHandler:

[legend]

Classes
struct	Callbacks

class	StringPairHash

Public Types
using	ParameterEventCallbackType = ParameterEventCallbackHandle::ParameterEventCallbackType

using	ParameterCallbackType = ParameterCallbackHandle::ParameterCallbackType

using	CallbacksContainerType = std::list< ParameterCallbackHandle::WeakPtr >

Public Member Functions
template<typename NodeT >
	ParameterEventHandler (const NodeT &node, const rclcpp::QoS &qos=rclcpp::QoS(rclcpp::QoSInitialization::from_rmw(rmw_qos_profile_parameter_events)))
	Construct a parameter events monitor. More...

RCLCPP_PUBLIC RCUTILS_WARN_UNUSED ParameterEventCallbackHandle::SharedPtr	add_parameter_event_callback (const ParameterEventCallbackType &callback)
	Set a callback for all parameter events. More...

RCLCPP_PUBLIC void	remove_parameter_event_callback (const ParameterEventCallbackHandle::SharedPtr &callback_handle)
	Remove parameter event callback registered with add_parameter_event_callback. More...

RCLCPP_PUBLIC RCUTILS_WARN_UNUSED ParameterCallbackHandle::SharedPtr	add_parameter_callback (const std::string &parameter_name, const ParameterCallbackType &callback, const std::string &node_name="")
	Add a callback for a specified parameter. More...

RCLCPP_PUBLIC bool	configure_nodes_filter (const std::vector< std::string > &node_names)
	Configure which node parameter events will be received. More...

RCLCPP_PUBLIC void	remove_parameter_callback (const ParameterCallbackHandle::SharedPtr &callback_handle)
	Remove a parameter callback registered with add_parameter_callback. More...

Static Public Member Functions
static RCLCPP_PUBLIC bool	get_parameter_from_event (const rcl_interfaces::msg::ParameterEvent &event, rclcpp::Parameter &parameter, const std::string &parameter_name, const std::string &node_name="")
	Get an rclcpp::Parameter from a parameter event. More...

static RCLCPP_PUBLIC rclcpp::Parameter	get_parameter_from_event (const rcl_interfaces::msg::ParameterEvent &event, const std::string &parameter_name, const std::string &node_name="")
	Get an rclcpp::Parameter from parameter event. More...

static RCLCPP_PUBLIC std::vector< rclcpp::Parameter >	get_parameters_from_event (const rcl_interfaces::msg::ParameterEvent &event)
	Get all rclcpp::Parameter values from a parameter event. More...

Protected Member Functions
std::string	resolve_path (const std::string &path)

Protected Attributes
std::shared_ptr< Callbacks >	callbacks_

std::shared_ptr< rclcpp::node_interfaces::NodeBaseInterface >	node_base_

rclcpp::Subscription< rcl_interfaces::msg::ParameterEvent >::SharedPtr	event_subscription_

Detailed Description

A class used to "handle" (monitor and respond to) changes to parameters.

The ParameterEventHandler class allows for the monitoring of changes to node parameters, either a node's own parameters or parameters owned by other nodes in the system. Multiple parameter callbacks can be set and will be invoked when the specified parameter changes.

The first step is to instantiate a ParameterEventHandler, providing a ROS node to use to create any required subscriptions:

auto param_handler = std::make_shared<rclcpp::ParameterEventHandler>(node);

Next, you can supply a callback to the add_parameter_callback method, as follows:

auto cb1 = [&node](const rclcpp::Parameter & p) {
   RCLCPP_INFO(
     node->get_logger(),
     "cb1: Received an update to parameter \"%s\" of type %s: \"%ld\"",
     p.get_name().c_str(),
     p.get_type_name().c_str(),
     p.as_int());
};
auto handle1 = param_handler->add_parameter_callback("an_int_param", cb1);

In this case, we didn't supply a node name (the third, optional, parameter) so the default will be to monitor for changes to the "an_int_param" parameter associated with 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:

auto cb2 = [&node](const rclcpp::Parameter & p) {
    RCLCPP_INFO(
      node->get_logger(),
      "cb2: Received an update to parameter \"%s\" of type: %s: \"%s\"",
      p.get_name().c_str(),
      p.get_type_name().c_str(),
      p.as_string().c_str());
  };
auto handle2 = param_handler->add_parameter_callback(
  "some_remote_param_name", cb2, "some_remote_node_name");

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, 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);

You can also monitor for all parameter changes, using add_parameter_event_callback. In this case, the callback will be invoked whenever any parameter changes in the system. You are likely interested in a subset of these parameter changes, so in the callback it is convenient to use a regular expression on the node names or namespaces of interest. For example:

auto cb3 =
  [fqn, remote_param_name, &node](const rcl_interfaces::msg::ParameterEvent & event) {
    // Look for any updates to parameters in "/a_namespace" as well as any parameter changes
    // to our own node ("this_node")
    std::regex re("(/a_namespace/.*)|(/this_node)");
    if (regex_match(event.node, re)) {
      // Now that we know the event matches the regular expression we scanned for, we can
      // use 'get_parameter_from_event' to get a specific parameter name that we're looking for
      rclcpp::Parameter p;
      if (rclcpp::ParameterEventHandler::get_parameter_from_event(
          event, p, remote_param_name, fqn))
      {
        RCLCPP_INFO(
          node->get_logger(),
          "cb3: Received an update to parameter \"%s\" of type: %s: \"%s\"",
          p.get_name().c_str(),
          p.get_type_name().c_str(),
          p.as_string().c_str());
      }
 
      // You can also use 'get_parameter*s*_from_event' to enumerate all changes that came
      // in on this event
      auto params = rclcpp::ParameterEventHandler::get_parameters_from_event(event);
      for (auto & p : params) {
        RCLCPP_INFO(
          node->get_logger(),
          "cb3: Received an update to parameter \"%s\" of type: %s: \"%s\"",
          p.get_name().c_str(),
          p.get_type_name().c_str(),
          p.value_to_string().c_str());
      }
    }
  };
auto handle3 = param_handler->add_parameter_event_callback(cb3);

For both parameter callbacks and parameter event callbacks, when multiple callbacks are added, the callbacks are invoked last-in, first-called order (LIFO).

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(handle3);

Definition at line 177 of file parameter_event_handler.hpp.

Constructor & Destructor Documentation

◆ ParameterEventHandler()

template<typename NodeT >

rclcpp::ParameterEventHandler::ParameterEventHandler	(	const NodeT &	node,
		const rclcpp::QoS &	qos = `rclcpp::QoS(rclcpp::QoSInitialization::from_rmw(rmw_qos_profile_parameter_events))`
	)

inlineexplicit

Construct a parameter events monitor.

Parameters

[in]	node	The node to use to create any required subscribers.
[in]	qos	The QoS settings to use for any subscriptions.

Definition at line 186 of file parameter_event_handler.hpp.

Member Function Documentation

◆ add_parameter_callback()

ParameterCallbackHandle::SharedPtr rclcpp::ParameterEventHandler::add_parameter_callback	(	const std::string &	parameter_name,
		const ParameterCallbackType &	callback,
		const std::string &	node_name = `""`
	)

Add a callback for a specified parameter.

If a node_name is not provided, defaults to the current node.

The configure_nodes_filter() function will affect the behavior of this function. If the node specified in this function isn't included in the nodes specified in configure_nodes_filter(), the callback will never be called.

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.

Parameters

[in]	parameter_name	Name of parameter to monitor.
[in]	callback	Function callback to be invoked upon parameter update.
[in]	node_name	Name of node which hosts the parameter.

Returns: A handle used to refer to the callback.

Definition at line 59 of file parameter_event_handler.cpp.

◆ add_parameter_event_callback()

ParameterEventCallbackHandle::SharedPtr rclcpp::ParameterEventHandler::add_parameter_event_callback ( const ParameterEventCallbackType & callback )

Set a callback for all parameter events.

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.

Parameters

[in] callback Function callback to be invoked on parameter updates.

Returns: A handle used to refer to the callback.

Definition at line 29 of file parameter_event_handler.cpp.

◆ configure_nodes_filter()

bool rclcpp::ParameterEventHandler::configure_nodes_filter ( const std::vector< std::string > & node_names )

Configure which node parameter events will be received.

This function depends on rmw implementation support for content filtering. If middleware doesn't support contentfilter, return false.

If node_names is empty, the configured node filter will be cleared.

If this function return true, only parameter events from the specified node will be received. It affects the behavior of the following two functions.

add_parameter_event_callback() The callback will only be called for parameter events from the specified nodes which are configured in this function.
add_parameter_callback() The callback will only be called for parameter events from the specified nodes which are configured in this function and add_parameter_callback(). If the nodes specified in this function is different from the nodes specified in add_parameter_callback(), the callback will never be called.

Parameters

[in] node_names Node names to filter parameter events from.

Returns: true if configuring was successfully applied, false otherwise.

Exceptions

rclcpp::exceptions::RCLError if internal error occurred when calling the rcl function.

Definition at line 78 of file parameter_event_handler.cpp.

References rclcpp::SubscriptionBase::is_cft_enabled(), rclcpp::SubscriptionBase::is_cft_supported(), and rclcpp::SubscriptionBase::set_content_filter().

Here is the call graph for this function:

◆ get_parameter_from_event() [1/2]

rclcpp::Parameter rclcpp::ParameterEventHandler::get_parameter_from_event	(	const rcl_interfaces::msg::ParameterEvent &	event,
		const std::string &	parameter_name,
		const std::string &	node_name = `""`
	)

static

Get an rclcpp::Parameter from parameter event.

If a node_name is not provided, defaults to the current node.

The user is responsible to check if the returned parameter has been properly assigned. By default, if the requested parameter is not found in the event, the returned parameter has parameter value of type rclcpp::PARAMETER_NOT_SET.

Parameters

[in]	event	Event msg to be inspected.
[in]	parameter_name	Name of parameter.
[in]	node_name	Name of node which hosts the parameter.

Returns: The resultant rclcpp::Parameter from the event.

Exceptions

std::runtime_error if input node name doesn't match the node name in parameter event.

Definition at line 166 of file parameter_event_handler.cpp.

References get_parameter_from_event().

Here is the call graph for this function:

◆ get_parameter_from_event() [2/2]

bool rclcpp::ParameterEventHandler::get_parameter_from_event	(	const rcl_interfaces::msg::ParameterEvent &	event,
		rclcpp::Parameter &	parameter,
		const std::string &	parameter_name,
		const std::string &	node_name = `""`
	)

static

Get an rclcpp::Parameter from a parameter event.

If a node_name is not provided, defaults to the current node.

Parameters

[in]	event	Event msg to be inspected.
[out]	parameter	Reference to rclcpp::Parameter to be assigned.
[in]	parameter_name	Name of parameter.
[in]	node_name	Name of node which hosts the parameter.

Returns: Output parameter is set with requested parameter info and returns true if requested parameter name and node is in event. Otherwise, returns false.

Definition at line 138 of file parameter_event_handler.cpp.

References rclcpp::Parameter::from_parameter_msg().

Referenced by rclcpp::ParameterEventHandler::Callbacks::event_callback(), and get_parameter_from_event().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_parameters_from_event()

std::vector< rclcpp::Parameter > rclcpp::ParameterEventHandler::get_parameters_from_event ( const rcl_interfaces::msg::ParameterEvent & event )

static

Get all rclcpp::Parameter values from a parameter event.

Parameters

[in] event Event msg to be inspected.

Returns: A vector rclcpp::Parameter values from the event.

Definition at line 185 of file parameter_event_handler.cpp.

References rclcpp::Parameter::from_parameter_msg().

Here is the call graph for this function:

◆ remove_parameter_callback()

void rclcpp::ParameterEventHandler::remove_parameter_callback ( const ParameterCallbackHandle::SharedPtr & callback_handle )

Remove a parameter callback registered with add_parameter_callback.

The parameter name and node name are inspected from the callback handle. The callback handle is erased from the list of callback handles on the {parameter_name, node_name} in the map. An error is thrown if the handle does not exist and/or was already removed.

Parameters

[in] callback_handle Handle of the callback to remove.

Definition at line 115 of file parameter_event_handler.cpp.

◆ remove_parameter_event_callback()

void rclcpp::ParameterEventHandler::remove_parameter_event_callback ( const ParameterEventCallbackHandle::SharedPtr & callback_handle )

Remove parameter event callback registered with add_parameter_event_callback.

Parameters

[in] callback_handle Handle of the callback to remove.

Definition at line 41 of file parameter_event_handler.cpp.

The documentation for this class was generated from the following files:

rclcpp/include/rclcpp/parameter_event_handler.hpp
rclcpp/src/rclcpp/parameter_event_handler.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ParameterEventHandler()

Member Function Documentation

◆ add_parameter_callback()

◆ add_parameter_event_callback()

◆ configure_nodes_filter()

◆ get_parameter_from_event() [1/2]

◆ get_parameter_from_event() [2/2]

◆ get_parameters_from_event()

◆ remove_parameter_callback()

◆ remove_parameter_event_callback()