contrib/hwloc/include/hwloc/diff.h

   1 /*
   2  * Copyright © 2013-2018 Inria.  All rights reserved.
   3  * See COPYING in top-level directory.
   4  */
   5
   6 /** \file
   7  * \brief Topology differences.
   8  */
   9
  10 #ifndef HWLOC_DIFF_H
  11 #define HWLOC_DIFF_H
  12
  13 #ifndef HWLOC_H
  14 #error Please include the main hwloc.h instead
  15 #endif
  16
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #elif 0
  21 }
  22 #endif
  23
  24
  25 /** \defgroup hwlocality_diff Topology differences
  26  *
  27  * Applications that manipulate many similar topologies, for instance
  28  * one for each node of a homogeneous cluster, may want to compress
  29  * topologies to reduce the memory footprint.
  30  *
  31  * This file offers a way to manipulate the difference between topologies
  32  * and export/import it to/from XML.
  33  * Compression may therefore be achieved by storing one topology
  34  * entirely while the others are only described by their differences
  35  * with the former.
  36  * The actual topology can be reconstructed when actually needed by
  37  * applying the precomputed difference to the reference topology.
  38  *
  39  * This interface targets very similar nodes.
  40  * Only very simple differences between topologies are actually
  41  * supported, for instance a change in the memory size, the name
  42  * of the object, or some info attribute.
  43  * More complex differences such as adding or removing objects cannot
  44  * be represented in the difference structures and therefore return
  45  * errors.
  46  * Differences between object sets cannot be represented either.
  47  *
  48  * It means that there is no need to apply the difference when
  49  * looking at the tree organization (how many levels, how many
  50  * objects per level, what kind of objects, CPU and node sets, etc)
  51  * and when binding to objects.
  52  * However the difference must be applied when looking at object
  53  * attributes such as the name, the memory size or info attributes.
  54  *
  55  * @{
  56  */
  57
  58
  59 /** \brief Type of one object attribute difference.
  60  */
  61 typedef enum hwloc_topology_diff_obj_attr_type_e {
  62   /** \brief The object local memory is modified.
  63    * The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s
  64    * (and the index field is ignored).
  65    */
  66   HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE,
  67
  68   /** \brief The object name is modified.
  69    * The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s
  70    * (and the name field is ignored).
  71    */
  72
  73   HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME,
  74   /** \brief the value of an info attribute is modified.
  75    * The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s.
  76    */
  77   HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
  78 } hwloc_topology_diff_obj_attr_type_t;
  79
  80 /** \brief One object attribute difference.
  81  */
  82 union hwloc_topology_diff_obj_attr_u {
  83   struct hwloc_topology_diff_obj_attr_generic_s {
  84     /* each part of the union must start with these */
  85     hwloc_topology_diff_obj_attr_type_t type;
  86   } generic;
  87
  88   /** \brief Integer attribute modification with an optional index. */
  89   struct hwloc_topology_diff_obj_attr_uint64_s {
  90     /* used for storing integer attributes */
  91     hwloc_topology_diff_obj_attr_type_t type;
  92     hwloc_uint64_t index; /* not used for SIZE */
  93     hwloc_uint64_t oldvalue;
  94     hwloc_uint64_t newvalue;
  95   } uint64;
  96
  97   /** \brief String attribute modification with an optional name */
  98   struct hwloc_topology_diff_obj_attr_string_s {
  99     /* used for storing name and info pairs */
 100     hwloc_topology_diff_obj_attr_type_t type;
 101     char *name; /* not used for NAME */
 102     char *oldvalue;
 103     char *newvalue;
 104   } string;
 105 };
 106
 107
 108 /** \brief Type of one element of a difference list.
 109  */
 110 typedef enum hwloc_topology_diff_type_e {
 111   /** \brief An object attribute was changed.
 112    * The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_s.
 113    */
 114   HWLOC_TOPOLOGY_DIFF_OBJ_ATTR,
 115
 116   /** \brief The difference is too complex,
 117    * it cannot be represented. The difference below
 118    * this object has not been checked.
 119    * hwloc_topology_diff_build() will return 1.
 120    *
 121    * The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_too_complex_s.
 122    */
 123   HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
 124 } hwloc_topology_diff_type_t;
 125
 126 /** \brief One element of a difference list between two topologies.
 127  */
 128 typedef union hwloc_topology_diff_u {
 129   struct hwloc_topology_diff_generic_s {
 130     /* each part of the union must start with these */
 131     hwloc_topology_diff_type_t type;
 132     union hwloc_topology_diff_u * next; /* pointer to the next element of the list, or NULL */
 133   } generic;
 134
 135   /* A difference in an object attribute. */
 136   struct hwloc_topology_diff_obj_attr_s {
 137     hwloc_topology_diff_type_t type; /* must be ::HWLOC_TOPOLOGY_DIFF_OBJ_ATTR */
 138     union hwloc_topology_diff_u * next;
 139     /* List of attribute differences for a single object */
 140     unsigned obj_depth;
 141     unsigned obj_index;
 142     union hwloc_topology_diff_obj_attr_u diff;
 143   } obj_attr;
 144
 145   /* A difference that is too complex. */
 146   struct hwloc_topology_diff_too_complex_s {
 147     hwloc_topology_diff_type_t type; /* must be ::HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX */
 148     union hwloc_topology_diff_u * next;
 149     /* Where we had to stop computing the diff in the first topology */
 150     unsigned obj_depth;
 151     unsigned obj_index;
 152   } too_complex;
 153 } * hwloc_topology_diff_t;
 154
 155
 156 /** \brief Compute the difference between 2 topologies.
 157  *
 158  * The difference is stored as a list of ::hwloc_topology_diff_t entries
 159  * starting at \p diff.
 160  * It is computed by doing a depth-first traversal of both topology trees
 161  * simultaneously.
 162  *
 163  * If the difference between 2 objects is too complex to be represented
 164  * (for instance if some objects have different types, or different numbers
 165  * of children), a special diff entry of type ::HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
 166  * is queued.
 167  * The computation of the diff does not continue below these objects.
 168  * So each such diff entry means that the difference between two subtrees
 169  * could not be computed.
 170  *
 171  * \return 0 if the difference can be represented properly.
 172  *
 173  * \return 0 with \p diff pointing to NULL if there is no difference
 174  * between the topologies.
 175  *
 176  * \return 1 if the difference is too complex (see above). Some entries in
 177  * the list will be of type ::HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX.
 178  *
 179  * \return -1 on any other error.
 180  *
 181  * \note \p flags is currently not used. It should be 0.
 182  *
 183  * \note The output diff has to be freed with hwloc_topology_diff_destroy().
 184  *
 185  * \note The output diff can only be exported to XML or passed to
 186  * hwloc_topology_diff_apply() if 0 was returned, i.e. if no entry of type
 187  * ::HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is listed.
 188  *
 189  * \note The output diff may be modified by removing some entries from
 190  * the list. The removed entries should be freed by passing them to
 191  * to hwloc_topology_diff_destroy() (possible as another list).
 192 */
 193 HWLOC_DECLSPEC int hwloc_topology_diff_build(hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff);
 194
 195 /** \brief Flags to be given to hwloc_topology_diff_apply().
 196  */
 197 enum hwloc_topology_diff_apply_flags_e {
 198   /** \brief Apply topology diff in reverse direction.
 199    * \hideinitializer
 200    */
 201   HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE = (1UL<<0)
 202 };
 203
 204 /** \brief Apply a topology diff to an existing topology.
 205  *
 206  * \p flags is an OR'ed set of ::hwloc_topology_diff_apply_flags_e.
 207  *
 208  * The new topology is modified in place. hwloc_topology_dup()
 209  * may be used to duplicate it before patching.
 210  *
 211  * If the difference cannot be applied entirely, all previous applied
 212  * elements are unapplied before returning.
 213  *
 214  * \return 0 on success.
 215  *
 216  * \return -N if applying the difference failed while trying
 217  * to apply the N-th part of the difference. For instance -1
 218  * is returned if the very first difference element could not
 219  * be applied.
 220  */
 221 HWLOC_DECLSPEC int hwloc_topology_diff_apply(hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags);
 222
 223 /** \brief Destroy a list of topology differences.
 224  *
 225  * \note The \p topology parameter must be a valid topology
 226  * but it is not required that it is related to \p diff.
 227  */
 228 HWLOC_DECLSPEC int hwloc_topology_diff_destroy(hwloc_topology_t topology, hwloc_topology_diff_t diff);
 229
 230 /** \brief Load a list of topology differences from a XML file.
 231  *
 232  * If not \c NULL, \p refname will be filled with the identifier
 233  * string of the reference topology for the difference file,
 234  * if any was specified in the XML file.
 235  * This identifier is usually the name of the other XML file
 236  * that contains the reference topology.
 237  *
 238  * \note The \p topology parameter must be a valid topology
 239  * but it is not required that it is related to \p diff.
 240  *
 241  * \note the pointer returned in refname should later be freed
 242  * by the caller.
 243  */
 244 HWLOC_DECLSPEC int hwloc_topology_diff_load_xml(hwloc_topology_t topology, const char *xmlpath, hwloc_topology_diff_t *diff, char **refname);
 245
 246 /** \brief Export a list of topology differences to a XML file.
 247  *
 248  * If not \c NULL, \p refname defines an identifier string
 249  * for the reference topology which was used as a base when
 250  * computing this difference.
 251  * This identifier is usually the name of the other XML file
 252  * that contains the reference topology.
 253  * This attribute is given back when reading the diff from XML.
 254  *
 255  * \note The \p topology parameter must be a valid topology
 256  * but it is not required that it is related to \p diff.
 257  */
 258 HWLOC_DECLSPEC int hwloc_topology_diff_export_xml(hwloc_topology_t topology, hwloc_topology_diff_t diff, const char *refname, const char *xmlpath);
 259
 260 /** \brief Load a list of topology differences from a XML buffer.
 261  *
 262  * If not \c NULL, \p refname will be filled with the identifier
 263  * string of the reference topology for the difference file,
 264  * if any was specified in the XML file.
 265  * This identifier is usually the name of the other XML file
 266  * that contains the reference topology.
 267  *
 268  * \note The \p topology parameter must be a valid topology
 269  * but it is not required that it is related to \p diff.
 270  *
 271  * \note the pointer returned in refname should later be freed
 272  * by the caller.
 273   */
 274 HWLOC_DECLSPEC int hwloc_topology_diff_load_xmlbuffer(hwloc_topology_t topology, const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname);
 275
 276 /** \brief Export a list of topology differences to a XML buffer.
 277  *
 278  * If not \c NULL, \p refname defines an identifier string
 279  * for the reference topology which was used as a base when
 280  * computing this difference.
 281  * This identifier is usually the name of the other XML file
 282  * that contains the reference topology.
 283  * This attribute is given back when reading the diff from XML.
 284  *
 285  * The returned buffer ends with a \0 that is included in the returned
 286  * length.
 287  *
 288  * \note The XML buffer should later be freed with hwloc_free_xmlbuffer().
 289  *
 290  * \note The \p topology parameter must be a valid topology
 291  * but it is not required that it is related to \p diff.
 292  */
 293 HWLOC_DECLSPEC int hwloc_topology_diff_export_xmlbuffer(hwloc_topology_t topology, hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen);
 294
 295 /** @} */
 296
 297
 298 #ifdef __cplusplus
 299 } /* extern "C" */
 300 #endif
 301
 302
 303 #endif /* HWLOC_DIFF_H */