API: add hwloc_modify_infos() to add/replace/remove info attrs

hwloc_obj_add_info() is now implemented on top of it.

Signed-off-by: Brice Goglin <[email protected]>

Author: bgoglin

NEWS

@@ -36,6 +36,7 @@ Version 3.0.0
     root object together with other backends.
   + The array and count of info attributes are now embedded in the new
     struct hwloc_infos_s.
+    - hwloc_infos_s structures may be modified with hwloc_modify_infos().
     - hwloc_cpukinds_get_info() and hwloc_cpukinds_register() now manipulate
       infos as such a structure.
 * Tools

doc/Makefile.am

@@ -350,7 +350,13 @@ man3_object_info_attrs_DATA = \
         $(DOX_MAN_DIR)/man3/hwlocality_info_attr.3 \
         $(DOX_MAN_DIR)/man3/hwloc_obj_get_info_by_name.3 \
         $(DOX_MAN_DIR)/man3/hwloc_get_info_by_name.3 \
-        $(DOX_MAN_DIR)/man3/hwloc_obj_add_info.3
+        $(DOX_MAN_DIR)/man3/hwloc_obj_add_info.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_modify_infos.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_modify_infos_op_e.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_MODIFY_INFOS_OP_ADD.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_MODIFY_INFOS_OP_ADD_UNIQUE.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_MODIFY_INFOS_OP_REPLACE.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_MODIFY_INFOS_OP_REMOVE.3
 
 man3_cpubindingdir = $(man3dir)
 man3_cpubinding_DATA = \

doc/hwloc.doxy

@@ -1970,7 +1970,7 @@ Each object contains a list of such pairs that may be consulted
 manually (looking at the object <tt>infos</tt> array field)
 or using the hwloc_obj_get_info_by_name().
 The user may additionally add new name-value pairs to any object using
-hwloc_obj_add_info() or the \ref cli_hwloc_annotate program.
+hwloc_obj_add_info(), hwloc_modify_infos() or the \ref cli_hwloc_annotate program.
 
 Here is a non-exhaustive list of attributes that may be automatically
 added by hwloc.
@@ -3970,7 +3970,7 @@ and <tt>hwloc_topology_set_userdata_import_callback()</tt>.
 Each object may also contain some <em>info</em> attributes
 (name and value strings) that are setup by hwloc during discovery
 and that may be extended by the user with
-<tt>hwloc_obj_add_info()</tt> (see also \ref attributes).
+<tt>hwloc_obj_add_info()</tt> or <tt>hwloc_modify_infos()</tt> (see also \ref attributes).
 Contrary to the <tt>userdata</tt> field which is unique, multiple info
 attributes may exist for each object, even with the same name.
 These attributes are always exported to XML.

hwloc/topology.c

@@ -523,6 +523,23 @@ int hwloc__add_info(struct hwloc_infos_s *infos, const char *name, const char *v
   return -1;
 }
 
+static int hwloc__add_info_unique(struct hwloc_infos_s *infos, const char *name, const char *value)
+{
+  struct hwloc_info_s *array = infos->array;
+  unsigned i, count = infos->count;
+
+  if (!name || !value) {
+    errno = EINVAL;
+    return -1;
+  }
+
+  for(i=0; i<count; i++)
+    if (!strcmp(array[i].name, name) && !strcmp(array[i].value, value))
+      return 0;
+
+  return hwloc__add_info(infos, name, value);
+}
+
 int hwloc__add_info_nodup(struct hwloc_infos_s *infos,
 			  const char *name, const char *value,
 			  int replace)
@@ -551,6 +568,92 @@ int hwloc__add_info_nodup(struct hwloc_infos_s *infos,
   return hwloc__add_info(infos, name, value);
 }
 
+static int hwloc__replace_infos(struct hwloc_infos_s *infos,
+                                const char *name, const char *value)
+{
+  struct hwloc_info_s *array = infos->array;
+  unsigned count = infos->count;
+  unsigned i;
+  int found = 0;
+
+  if (!name || !value) {
+    errno = EINVAL;
+    return -1;
+  }
+
+  for(i=0; i<count; i++) {
+    if (!strcmp(array[i].name, name)) {
+      if (!found) {
+        /* first match, replace */
+        char *new = strdup(value);
+        if (!new)
+	  return -1;
+	free(array[i].value);
+	array[i].value = new;
+      } else {
+        /* non-first match, remove */
+        free(array[i].name);
+        free(array[i].value);
+      }
+      found++;
+    } else if (found > 1) {
+      /* non-match, move left by found-1 */
+      array[i-(found-1)].name = array[i].name;
+      array[i-(found-1)].value = array[i].value;
+    }
+  }
+  if (found) {
+    if (found > 1)
+      infos->count -= found-1;
+    return 0;
+  } else {
+    /* no match, just add */
+    return hwloc__add_info(infos, name, value);
+  }
+}
+
+static int hwloc__remove_infos(struct hwloc_infos_s *infos,
+                        const char *name, const char *value)
+{
+  struct hwloc_info_s *array = infos->array;
+  unsigned count = infos->count;
+  unsigned i;
+  int found = 0;
+
+  for(i=0; i<count; i++) {
+    if ((!name || !strcmp(array[i].name, name))
+        && (!value || !strcmp(array[i].value, value))) {
+      /* match, remove */
+      free(array[i].name);
+      free(array[i].value);
+      found++;
+    } else {
+      /* non-match, move left by found */
+      array[i-found].name = array[i].name;
+      array[i-found].value = array[i].value;
+    }
+  }
+  infos->count -= found;
+  return 0;
+}
+
+int hwloc_modify_infos(struct hwloc_infos_s *infos, unsigned long op, const char *name, const char *value)
+{
+  switch (op) {
+  case HWLOC_MODIFY_INFOS_OP_ADD:
+    return hwloc__add_info(infos, name, value);
+  case HWLOC_MODIFY_INFOS_OP_ADD_UNIQUE:
+    return hwloc__add_info_unique(infos, name, value);
+  case HWLOC_MODIFY_INFOS_OP_REPLACE:
+    return hwloc__replace_infos(infos, name, value);
+  case HWLOC_MODIFY_INFOS_OP_REMOVE:
+    return hwloc__remove_infos(infos, name, value);
+  default:
+    errno = EINVAL;
+    return -1;
+  }
+}
+
 int hwloc__move_infos(struct hwloc_infos_s *dst_infos,
 		      struct hwloc_infos_s *src_infos)
 {
@@ -591,11 +694,6 @@ int hwloc__move_infos(struct hwloc_infos_s *dst_infos,
   return -1;
 }
 
-int hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value)
-{
-  return hwloc__add_info(&obj->infos, name, value);
-}
-
 /* This function may be called with topology->tma set, it cannot free() or realloc() */
 int hwloc__tma_dup_infos(struct hwloc_tma *tma,
                          struct hwloc_infos_s *newi,

include/hwloc.h

@@ -426,7 +426,8 @@ struct hwloc_info_s {
 
 /** \brief Array of string info attributes (pairs of name and value).
  *
- * These structures may only be modified with hwloc_obj_add_info().
+ * These structures may only be modified with hwloc_obj_add_info()
+ * and hwloc_modify_infos().
  *
  * \sa hwlocality_info_attr
  */
@@ -1155,10 +1156,61 @@ hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) __hwloc_attribute_
 static __hwloc_inline const char *
 hwloc_get_info_by_name(struct hwloc_infos_s *infos, const char *name) __hwloc_attribute_pure;
 
+/** \brief Modify an array of info attributes.
+ *
+ * \p operation is a single value among enum hwloc_modify_infos_op_e.
+ *
+ * If adding (::HWLOC_MODIFY_INFOS_OP_ADD or ::HWLOC_MODIFY_INFOS_OP_ADD_UNIQUE)
+ * or replacing (::HWLOC_MODIFY_INFOS_OP_REPLACE) an info attribute,
+ * \p name and \p value cannot be \c NULL.
+ * The input strings are copied before being added in the object infos.
+ *
+ * If removing existing info pairs (::HWLOC_MODIFY_INFOS_OP_REMOVE),
+ * \p name and/or \p value may be non \c NULL to specify which pair(s) to remove.
+ * If both \p name and \p value are \c NULL, all pairs are removed.
+ *
+ * \return \c 0 on success, \c -1 on error.
+ *
+ * \note If \p value contains some non-printable characters, they will
+ * be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.
+ */
+HWLOC_DECLSPEC int hwloc_modify_infos(struct hwloc_infos_s *infos,
+                                      unsigned long operation,
+                                      const char *name, const char *value);
+
+/** \brief Operations given to hwloc_modify_infos(). */
+enum hwloc_modify_infos_op_e {
+  /** \brief Add a new info attribute with the given name and value.
+   * \hideinitializer
+   */
+  HWLOC_MODIFY_INFOS_OP_ADD = 1UL<<0,
+
+  /** \brief Add a new info attribute with the given name and value
+   * only if that pair doesn't exist yet.
+   * \hideinitializer
+   */
+  HWLOC_MODIFY_INFOS_OP_ADD_UNIQUE = 1UL<<1,
+
+  /** \brief Replace existing info attributes with the given name,
+   * with a single attribute with the given name and value.
+   * If no existing pair matches, add a new one.
+   * If multiple pairs match, only one remains.
+   * \hideinitializer
+   */
+  HWLOC_MODIFY_INFOS_OP_REPLACE = 1UL<<2,
+
+  /** \brief Remove existing info attributes that matches the given
+   * name and/or value if not \c NULL.
+   * \hideinitializer
+   */
+  HWLOC_MODIFY_INFOS_OP_REMOVE = 1UL<<3
+};
+
 /** \brief Add the given name and value pair to the given object info attributes.
  *
  * The info pair is appended to the existing info array even if another pair
- * with the same name already exists.
+ * with the same name already exists. See hwloc_modify_infos() for a more
+ * flexible variant.
  *
  * The input strings are copied before being added in the object infos.
  *
@@ -1173,7 +1225,8 @@ hwloc_get_info_by_name(struct hwloc_infos_s *infos, const char *name) __hwloc_at
  * \note If \p name or \p value contain some non-printable characters, they will
  * be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.
  */
-HWLOC_DECLSPEC int hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
+static __hwloc_inline int
+hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
 
 /** @} */
 

include/hwloc/inlines.h

@@ -125,6 +125,12 @@ hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
   return hwloc_get_info_by_name(&obj->infos, name);
 }
 
+static __hwloc_inline int
+hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value)
+{
+  return hwloc_modify_infos(&obj->infos, HWLOC_MODIFY_INFOS_OP_ADD, name, value);
+}
+
 static __hwloc_inline void *
 hwloc_alloc_membind_policy(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t set, hwloc_membind_policy_t policy, int flags)
 {

include/hwloc/rename.h

@@ -218,6 +218,12 @@ extern "C" {
 #define hwloc_obj_get_info_by_name HWLOC_NAME(obj_get_info_by_name)
 #define hwloc_get_info_by_name HWLOC_NAME(get_info_by_name)
 #define hwloc_obj_add_info HWLOC_NAME(obj_add_info)
+#define hwloc_modify_infos HWLOC_NAME(modify_infos)
+#define hwloc_modify_infos_op_e HWLOC_NAME(modify_infos_op_e)
+#define HWLOC_MODIFY_INFOS_OP_ADD HWLOC_NAME_CAPS(MODIFY_INFOS_OP_ADD)
+#define HWLOC_MODIFY_INFOS_OP_ADD_UNIQUE HWLOC_NAME_CAPS(MODIFY_INFOS_OP_ADD_UNIQUE)
+#define HWLOC_MODIFY_INFOS_OP_REPLACE HWLOC_NAME_CAPS(MODIFY_INFOS_OP_REPLACE)
+#define HWLOC_MODIFY_INFOS_OP_REMOVE HWLOC_NAME_CAPS(MODIFY_INFOS_OP_REMOVE)
 
 #define HWLOC_CPUBIND_PROCESS HWLOC_NAME_CAPS(CPUBIND_PROCESS)
 #define HWLOC_CPUBIND_THREAD HWLOC_NAME_CAPS(CPUBIND_THREAD)