Function rmw_get_node_names

Function Documentation

rmw_ret_t rmw_get_node_names(const rmw_node_t *node, rcutils_string_array_t *node_names, rcutils_string_array_t *node_namespaces)

Return the name and namespace of all nodes in the ROS graph.

This function will return an array of node names and an array of node namespaces, as discovered so far by the given node. The two arrays represent name and namespace pairs for each discovered node. Both arrays will be the same length and the same index will refer to the same node.

Attribute

Adherence

Allocates Memory

Yes

Thread-Safe

No

Uses Atomics

Maybe [1]

Lock-Free

Maybe [1]

[1] implementation defined, check the implementation documentation

Runtime behavior

To query the ROS graph is a synchronous operation. It is also non-blocking, but it is not guaranteed to be lock-free. Generally speaking, implementations may synchronize access to internal resources using locks but are not allowed to wait for events with no guaranteed time bound (barring the effects of starvation due to OS scheduling).

Thread-safety

Nodes are thread-safe objects, and so are all operations on them except for finalization. Therefore, it is safe to query the ROS graph using the same node concurrently. However, access to string arrays is not synchronized. It is not safe to read or write node_names nor node_namespaces while rmw_get_node_names() uses them.

Parameters:

  • node – [in] Node to query the ROS graph.

  • node_names – [out] Array of discovered node names, populated on success. It is up to the caller to finalize this array later on, using rcutils_string_array_fini().

  • node_namespaces – [out] Array of discovered node namespaces, populated on success. It is up to the caller to finalize this array later on, using rcutils_string_array_fini().

Pre:

Given node must be a valid node handle, as returned by rmw_create_node().

Pre:

Given node_names must be a valid string array, zero-initialized as returned by rcutils_get_zero_initialized_string_array().

Pre:

Given node_namespaces must be a valid string array, zero-initialized as returned by rcutils_get_zero_initialized_string_array().

Post:

Given node_names and node_namespaces will remain valid arrays. These will be left unchanged if this function fails early due to a logical error, such as an invalid argument, or in an unknown yet valid state if it fails due to a runtime error.

Returns:

RMW_RET_OK if the query was successful, or

Returns:

RMW_RET_INVALID_ARGUMENT if node is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if node_names is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if node_names is not a zero-initialized array, or

Returns:

RMW_RET_INVALID_ARGUMENT if node_namespaces is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if node_namespaces is not a zero-initialized array, or

Returns:

RMW_RET_INCORRECT_RMW_IMPLEMENTATION if the node implementation identifier does not match this implementation, or

Returns:

RMW_RET_BAD_ALLOC if memory allocation fails, or

Returns:

RMW_RET_ERROR if an unspecified error occurs.