Merge pull request #9297 from tvegas1/uct_rkey_compare_api

UCT/API: Add uct_rkey_compare() function

src/uct/api/uct.h

@@ -826,6 +826,15 @@ enum uct_md_mem_flags {
      */
     UCT_MD_MEM_ACCESS_LOCAL_WRITE   = UCS_BIT(9),
 
+    /**
+     * Register the memory region so its remote access key would likely be
+     * equal to remote access keys received from other peers, when compared
+     * with @a uct_rkey_compare. This flag is a hint. When remote access keys
+     * received from different peers are compared equal, they can be used
+     * interchangeably, avoiding the need to keep all of them in memory.
+     */
+    UCT_MD_MEM_SYMMETRIC_RKEY       = UCS_BIT(10),
+
     /**
      * Enable local and remote access for all operations.
      */

src/uct/api/v2/uct_v2.h

@@ -663,6 +663,19 @@ typedef struct uct_ep_connect_to_ep_params {
 } uct_ep_connect_to_ep_params_t;
 
 
+/**
+ * @ingroup UCT_MD
+ * @brief Parameters for comparing remote keys using @ref uct_rkey_compare.
+ */
+typedef struct uct_rkey_compare_params {
+    /**
+     * Mask of valid fields in this structure. Must currently be equal to zero.
+     * Fields not specified in this mask will be ignored. Provides ABI
+     * compatibility with respect to adding new fields.
+     */
+    uint64_t                      field_mask;
+} uct_rkey_compare_params_t;
+
 /**
  * @ingroup UCT_RESOURCE
  * @brief Get interface performance attributes, by memory types and operation.
@@ -1036,6 +1049,28 @@ ucs_status_t uct_ep_connect_to_ep_v2(uct_ep_h ep,
 int uct_ep_is_connected(uct_ep_h ep,
                         const uct_ep_is_connected_params_t *params);
 
+/**
+ * @ingroup UCT_MD
+ *
+ * @brief This routine compares two remote keys.
+ *
+ * It sets the @a result argument to < 0 if rkey1 is lower than rkey2, 0 if they
+ * are equal or > 0 if rkey1 is greater than rkey2. The result value can be used
+ * for sorting remote keys.
+ *
+ * @param[in]  component  Component to use for the comparison
+ * @param[in]  rkey1      First rkey to compare
+ * @param[in]  rkey2      Second rkey to compare
+ * @param[in]  params     Additional parameters for comparison
+ * @param[out] result     Result of the comparison
+ *
+ * @return UCS_OK         @a result contains the comparison result
+ *         Other          Error codes as defined by @ref ucs_status_t.
+ */
+ucs_status_t
+uct_rkey_compare(uct_component_h component, uct_rkey_t rkey1, uct_rkey_t rkey2,
+                 const uct_rkey_compare_params_t *params, int *result);
+
 END_C_DECLS
 
 #endif

src/uct/base/uct_md.c

@@ -361,6 +361,13 @@ ucs_status_t uct_rkey_release(uct_component_h component,
     return component->rkey_release(component, rkey_ob->rkey, rkey_ob->handle);
 }
 
+ucs_status_t
+uct_rkey_compare(uct_component_h component, uct_rkey_t rkey1, uct_rkey_t rkey2,
+                 const uct_rkey_compare_params_t *params, int *result)
+{
+    return UCS_ERR_UNSUPPORTED;
+}
+
 static void uct_md_attr_from_v2(uct_md_attr_t *dst, const uct_md_attr_v2_t *src)
 {
     dst->cap.max_alloc        = src->max_alloc;