From efee9253cecfea23279654284a868ec5acb8ccfa Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Thu, 13 Oct 2022 11:27:48 -0700 Subject: [PATCH] Update documented expectations for GIDs * Clarify that GIDs are globally unique within a ROS domain. * Specify that any unused bytes in the GID should be set to zero (e.g. in cases where not all 24 bytes are used). This allows application code to directly compare GIDs without having to ask the middleware. Signed-off-by: Jacob Perron --- rmw/include/rmw/rmw.h | 25 ++++++++++++++++--------- rmw/include/rmw/types.h | 9 +++++++-- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index 2e9b4286..cc197bdc 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -3039,7 +3039,7 @@ rmw_count_services( const char * service_name, size_t * count); -/// Get the unique identifier (gid) of a publisher. +/// Get the globally unique identifier (GID) of a publisher. /** *
* Attribute | Adherence @@ -3055,12 +3055,16 @@ rmw_count_services( * Publishers 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 publisher concurrently. - * However, access to the gid is not synchronized. + * However, access to the GID is not synchronized. * It is not safe to read or write `gid` while rmw_get_gid_for_publisher() uses it. * * \pre Given `publisher` must be a valid publisher, as returned by rmw_create_publisher(). * - * \param[in] publisher Publisher to get a gid from. + * This is expected to be globally unique within a ROS domain. + * The identifier should be the same when reported both locally (where the entity was created) + * and on remote hosts or processes. + * + * \param[in] publisher Publisher to get a GID from. * \param[out] gid Publisher's unique identifier, populated on success * but left unchanged on failure. * \return `RMW_RET_OK` if successful, or @@ -3075,7 +3079,7 @@ 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. +/// Get the globally unique identifier (GID) of a service client. /** *
* Attribute | Adherence @@ -3091,12 +3095,15 @@ rmw_get_gid_for_publisher(const rmw_publisher_t * publisher, rmw_gid_t * gid); * 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. + * 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. + * This is expected to be globally unique within a ROS domain. + * The identifier should be the same when reported both locally (where the entity was created) + * and on remote hosts or processes. + * \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 @@ -3111,7 +3118,7 @@ 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. +/// Check if two globally unique identifiers (GIDs) are equal. /** *
* Attribute | Adherence @@ -3125,14 +3132,14 @@ rmw_get_gid_for_client(const rmw_client_t * client, rmw_gid_t * gid); * * \par Thread-safety * Unique identifier comparison is a reentrant function, but: - * - Access to both gids is read-only but it is not synchronized. + * - Access to both GIDs is read-only but it is not synchronized. * Concurrent `gid1` and `gid2` reads are safe, but concurrent reads and writes are not. * - Access to primitive data-type arguments is not synchronized. * It is not safe to read or write `result` while rmw_compare_gids_equal() uses it. * * \param[in] gid1 First unique identifier to compare. * \param[in] gid2 Second unique identifier to compare. - * \param[out] result true if both gids are equal, false otherwise. + * \param[out] result true if both GIDs are equal, false otherwise. * \return `RMW_RET_OK` if successful, or * \return `RMW_RET_INVALID_ARGUMENT` if `gid1` or `gid2` is NULL, or * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index 95ac2592..9fc101ab 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -618,13 +618,18 @@ typedef struct RMW_PUBLIC_TYPE rmw_qos_profile_s bool avoid_ros_namespace_conventions; } rmw_qos_profile_t; -/// ROS graph ID of the topic +/// Globally unique identifier for a ROS graph entity +/** + * This is expected to be globally unique within a ROS domain. + * The identifier should be the same when reported both locally (where the entity was created) + * and on remote hosts or processes. + */ typedef struct RMW_PUBLIC_TYPE rmw_gid_s { /// Name of the rmw implementation const char * implementation_identifier; - /// Byte data Gid value + /// Byte data GID value uint8_t data[RMW_GID_STORAGE_SIZE]; } rmw_gid_t;