Function rmw_get_clients_info_by_service

Function Documentation

rmw_ret_t rmw_get_clients_info_by_service(const rmw_node_t *node, rcutils_allocator_t *allocator, const char *service_name, bool no_mangle, rmw_service_endpoint_info_array_t *clients_info)

Retrieve endpoint information for each known client of a given service.

This function returns an array of endpoint information for each client of a given service, as discovered so far by the given node. Endpoint information includes the client’s node name and namespace, the associated service type, the client’s gid, and the client QoS profile. Names of non-existent services are allowed, in which case an empty array will be returned.

Depending on the RMW in use, discovery may be asynchronous. Therefore, creating a client and then calling this API may not show the newly created client immediately.

Other middleware implementations, such as Zenoh, may offer native support for services, without using topics internally. This API is designed to support both models and can return endpoint information regardless of the underlying implementation strategy.

Internal behavior

The internal representation of services depends on the underlying RMW implementation. For example, in DDS-based RMWs, services are implemented using two topics: one for requests and one for responses. The client and server each create both a DataReader and a DataWriter — the client writes requests and reads responses, while the server reads requests and writes responses. In this case, all fields of rmw_topic_endpoint_info_t can be queried from the graph cache.

Attribute

Adherence

Allocates Memory

Yes

Thread-Safe

Yes

Uses Atomics

Maybe [1]

Lock-Free

Maybe [1]

[1] rmw implementation defined, check the implementation documentation
QoS that are correctly read

The QoS profiles returned might have some invalid fields. The rmw implementation must set the invalid fields to RMW_QOS_POLICY_*_UNKNOWN. For DDS based implementations, the only QoS policies that are guaranteed to be shared during discovery are the ones that participate in endpoint matching. From the current QoS settings available, the only ones not shared by DDS based implementations are history and history_depth.

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, when querying service names and types:

  • Access to the array of service endpoint information is not synchronized. It is not safe to read or write clients_info while rmw_get_clients_info_by_service() uses it.

  • Access to C-style string arguments is read-only but it is not synchronized. Concurrent service_name reads are safe, but concurrent reads and writes are not.

  • The default allocators are thread-safe objects, but any custom allocator may not be. Check your allocator documentation for further reference.

Parameters:

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

  • allocator – [in] Allocator to be used when populating the clients_info array.

  • service_name – [in] Name of the service for client lookup, often a fully qualified service name but not necessarily (see rmw_create_client()).

  • no_mangle – [in] Whether to mangle the service name before client lookup or not. Note: DDS-based RMWs do not support no_mangle = true because services are implemented as topics with mangled names. Use rmw_get_publishers_info_by_topic or rmw_get_subscriptions_info_by_topic for unmangled topic queries in such cases. Other RMWs (e.g., Zenoh) may support no_mangle = true if they natively handle services without topic-based mangling.

  • clients_info – [out] Array of client information, populated on success, left unchanged on failure. If populated, it is up to the caller to finalize this array later on, using rmw_service_endpoint_info_array_fini(). QoS Profiles in the info array will use RMW_DURATION_INFINITE for infinite durations, avoiding exposing any implementation-specific values.

Pre:

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

Pre:

Given clients_info must be a zero-initialized array of endpoints’ information, as returned by rmw_get_zero_initialized_service_endpoint_info_array().

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 allocator is not valid, by rcutils_allocator_is_valid() definition, or

Returns:

RMW_RET_INVALID_ARGUMENT if service_name is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if clients_info is NULL, or

Returns:

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