Function rmw_get_node_names_with_enclaves

Function Documentation

rmw_ret_t rmw_get_node_names_with_enclaves(const rmw_node_t *node, rcutils_string_array_t *node_names, rcutils_string_array_t *node_namespaces, rcutils_string_array_t *enclaves)

Return the name, namespae, and enclave name of all nodes in the ROS graph.

This is similar to rmw_get_node_names(), but it also provides enclave names.

Attribute

Adherence

Allocates Memory

Yes

Thread-Safe

Yes

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, node_namespaces, nor enclaves while rmw_get_node_names_with_enclaves() 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().

  • enclaves – [out] Array of discovered node enclave names, 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().

Pre:

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

Post:

Given node_names, node_namespaces, and enclaves 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_INVALID_ARGUMENT if enclaves is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if enclaves 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.