From a060170d0562a7f12b175a9285a65dccdd090598 Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Mon, 15 Aug 2022 11:13:42 -0700 Subject: [PATCH 1/2] add rmw_get_gid_for_client Signed-off-by: Brian Chen --- rmw/include/rmw/rmw.h | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index f25c7b07..2f6a0089 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -2973,6 +2973,12 @@ RMW_WARN_UNUSED rmw_ret_t rmw_get_gid_for_publisher(const rmw_publisher_t * publisher, rmw_gid_t * gid); +RMW_PUBLIC +RMW_WARN_UNUSED +rmw_ret_t +rmw_get_gid_for_client(const rmw_client_t * client, rmw_gid_t * gid); + + /// Check if two unique identifiers (gids) are equal. /** *
From a404f195a324e585a27e520a22c0fa465e4255e5 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Mon, 19 Sep 2022 11:05:02 -0700 Subject: [PATCH 2/2] Add documentation and remove extra empty line Signed-off-by: Jacob Perron --- rmw/include/rmw/rmw.h | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index 2f6a0089..e25770e6 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -2973,12 +2973,42 @@ RMW_WARN_UNUSED rmw_ret_t rmw_get_gid_for_publisher(const rmw_publisher_t * publisher, rmw_gid_t * gid); +/// Get the unique identifier (gid) of a service client. +/** + *
+ * Attribute | Adherence + * ------------------ | ------------- + * Allocates Memory | No + * Thread-Safe | Yes + * Uses Atomics | Maybe [1] + * Lock-Free | Maybe [1] + * + * [1] implementation defined, check implementation documentation. + * + * \par Thread-safety + * Service clients are thread-safe objects, and so are all operations on them except for + * finalization. + * Therefore, it is safe to get the unique identifier from the same client concurrently. + * However, access to the gid is not synchronized. + * It is not safe to read or write `gid` while rmw_get_gid_for_client() uses it. + * + * \pre Given `client` must be a valid service client, as returned by rmw_create_client(). + * + * \param[in] client Service client to get a gid from. + * \param[out] gid Service client's unique identifier, populated on success + * but left unchanged on failure. + * \return `RMW_RET_OK` if successful, or + * \return `RMW_RET_INVALID_ARGUMENT` if `publisher` is NULL, or + * \return `RMW_RET_INVALID_ARGUMENT` if `gid` is NULL, or + * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the `client` implementation + * identifier does not match this implementation, or + * \return `RMW_RET_ERROR` if an unspecified error occurs. + */ RMW_PUBLIC RMW_WARN_UNUSED rmw_ret_t rmw_get_gid_for_client(const rmw_client_t * client, rmw_gid_t * gid); - /// Check if two unique identifiers (gids) are equal. /** *