From e52b31b86345e0a1b86eaa84d9a8ef62995cfcf9 Mon Sep 17 00:00:00 2001 From: Michel Hidalgo Date: Wed, 23 Sep 2020 16:37:09 -0300 Subject: [PATCH] Update rmw_server_is_available() API documentation. Signed-off-by: Michel Hidalgo --- rmw/include/rmw/rmw.h | 51 +++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 21 deletions(-) diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index b075aa26..12864c9e 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -2791,7 +2791,7 @@ rmw_get_node_names_with_enclaves( * * \par Thread-safety * Nodes are thread-safe objects, and so are all operations on them except for finalization. - * Therefore, it is to query the ROS graph using the same node concurrently. + * Therefore, it is safe to query the ROS graph using the same node concurrently. * However, access to primitive data-type arguments is not synchronized. * It is not safe to read or write `topic_name` or `count` while rmw_count_publishers() * uses them. @@ -2941,31 +2941,40 @@ rmw_compare_gids_equal(const rmw_gid_t * gid1, const rmw_gid_t * gid2, bool * re /// Check if a service server is available for the given service client. /** - * This function will return true for `is_available` if there is a service - * server available for the given client. + * This function checks whether one or more service services matching the + * given service client exist in the ROS graph, as discovered so far by the + * given local node. * - * The node parameter must not be `NULL`, and must point to a valid node. - * - * The client parameter must not be `NULL`, and must point to a valid client. + *
+ * Attribute | Adherence + * ------------------ | ------------- + * Allocates Memory | No + * Thread-Safe | Yes + * Uses Atomics | Maybe [1] + * Lock-Free | Maybe [1] * - * The given client and node must match, i.e. the client must have been created - * using the given node. + * [1] implementation defined, check implementation documentation. * - * The is_available parameter must not be `NULL`, and must point to a bool - * variable. - * The result of the check will be stored in the is_available parameter. + * \par 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). * - * This function does manipulate heap memory. - * This function is not thread-safe. - * This function is lock-free. + * \pre Given `node` must be a valid node, as returned by rmw_create_node(). + * \pre Given `client` must be a valid client, as returned by rmw_create_client(). + * \pre Given `node` must be the one the `client` was registered with. * - * \param[in] node the handle to the node being used to query the ROS graph - * \param[in] client the handle to the service client being queried - * \param[out] is_available - * set to true if there is a service server available, else false - * \return `RMW_RET_OK` if node the check was made successfully, or - * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the `publisher` implementation - * identifier does not match this implementation, or + * \param[in] node Node to query the ROS graph. + * \param[in] client Service client to look for matching service servers. + * \param[out] is_available True if there is a service server available, else false. + * \return `RMW_RET_OK` if successful, or + * \return `RMW_RET_INVALID_ARGUMENT` if `node` is `NULL`, or + * \return `RMW_RET_INVALID_ARGUMENT` if `client` is `NULL`, or + * \return `RMW_RET_INVALID_ARGUMENT` if `is_available` is `NULL`, or + * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation + * identifier of `node` or `client` does not match this implementation, or * \return `RMW_RET_ERROR` if an unspecified error occurs. */ RMW_PUBLIC