From 67b0f0a229c0bd665913a1d937ee82bf896ad554 Mon Sep 17 00:00:00 2001 From: Brian Date: Fri, 23 Sep 2022 10:09:49 -0700 Subject: [PATCH] Add rmw_get_gid_for_client method (#327) * add rmw_get_gid_for_client Signed-off-by: Brian Chen * Add documentation and remove extra empty line Signed-off-by: Brian Chen Signed-off-by: Jacob Perron Co-authored-by: Jacob Perron --- rmw/include/rmw/rmw.h | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index f25c7b07..e25770e6 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -2973,6 +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. /** *